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Preface 
Conventions Used in This Manual 

A/UX® manuals follow certain conventions regarding presentation of 
information. Words or terms that require special emphasis appear in 
specific fonts within the text of the manual. The following sections 
explain the conventions used in this manual. 

Significant fonts 

Words that you see on the screen or that you must type exactly as 
shown appear in Courier font. For example, when you begin an 
A/UX work session, you see the following on the screen: 

login: 

The text shows login: in Courier typeface to indicate that it 
appears on the screen. If the next step in the manual is 

Enter start 

start appears in Courier to indicate that you must type in the 
word. Words that you must replace with a value appropriate to a 
particular set of circumstances appear in italics. Using the example just 
described, if the next step in the manual is 

login: username 

you type in your name — Laura, for example — so the screen shows: 

login: Laura 

Key presses 

Certain keys are identified with names on the keyboard. These modifier 
and character keys perform functions, often in combination with other 
keys. In the manuals, the names of these keys appear in the format of 
an Initial Capital letter followed by small capital letters. 

The list that follows provides the most common keynames. 

Return Delete Shift Escape 

Option Caps lock Control 

For example, if you enter 
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Applee 
instead of 

Apple 

you would position the cursor to the right of the word and press the 
Delete key once to erase the additional e. 

For cases in which you use two or more keys together to perform a 
specific function, the keynames are shown connected with hyphens. 
For example, if you see 

Press Control-c 

you must press Control and c simultaneously (Control-c normally 
cancels the execution of the current command). 

Terminology 

In A/UX manuals, a certain term can represent a specific set of actions. 
For example, the word Enter indicates that you type in an entry and 
press the Return key. If you were to see 

Enter the following command: who ami 

you would type whoami and press the Return key. The system 
would then respond by identifying your login name. 

Here is a list of common terms and their corresponding actions. 

Term Action 

Enter Type in the entry and press the Return key 

Press Press a single letter or key without pressing the 

Return key 

Type Type in the letter or letters without pressing the 

Return key 

Click Press and then immediately release the mouse button 
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Term 
Select 



Action 

Position the pointer on an item and click the mouse 
button 



Drag 



Position the pointer on an icon, press and hold down 
the mouse button while moving the mouse. Release 
the mouse button when you reach the desired 
position. 



Choose Activate a command title in the menu bar. While 

holding down the mouse button, drag the pointer to a 
command name in the menu and then release the 
mouse button. An example is to drag the File menu 
down until the command name Open appears 
highlighted and then release the mouse button. 

Syntax notation 

A/UX commands follow a specific order of entry. A typical A/UX 
command has this form: 

command [flag-option] [argument] . . . 

The elements of a command have the following meanings. 



Element 



Description 



command Is the command name. 

flag-option Is one or more optional arguments that modify the 

command. Most flag-options have the form 

[-opt..] 
where opt is a letter representing an option. 
Commands can take one or more options. 

argument Is a modification or specification of the command; 

usually a filename or symbols representing one or 
more filenames. 



Revision C 



IX 



Element Description 

brackets ([ ]) Surround an optional item — that is, an item that you 
do not need to include for the command to execute. 

ellipses (...) Follow an argument that may be repeated any 
number of times. 

For example, the command to list the contents of a directory (Is) is 
followed below by its possible flag options and the optional argument 
names. 

Is [-R] [-a] [-d] [-C] [-x] [-m] [-1] [-L] 
[-n] [-o] [-g] [-r] [-t] [-u] [-c] [-p] [-F] 
[-b] [-q] [-i] [-s] [names] 

You can enter 

Is -a /users 

to list all entries of the directory /users, where 

1 s Represents the command name 

-a Indicates that all entries of the directory be listed 

/users Names which directory is to be listed 

Command reference notation 

Reference material is organized by section numbers. The standard 
A/UX cross-reference notation is 

cmd(sect) 

where cmd is the name of the command, file, or other facility; sect is 
the section number where the entry resides. 

□ Commands followed by section numbers (1M), (7), or (8) are listed 
in A/UX System Administrator' s Reference. 

□ Commands followed by section numbers (1), (1C), (1G), (IN), and 
(6) are listed in A/UX Command Reference. 

□ Commands followed by section numbers (2), (3), (4), and (5) are 
listed in A/UX Programmer's Reference. 
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For example, 

cat(l) 

refers to the command cat, which is described in Section 1 of A/UX 
Command Reference. References can also be called up on the screen. 
The man command or the apropos command displays pages from 
the reference manuals directly on the screen. For example, enter the 
command 

man cat 

In this example, the manual page for the cat command including its 
description, syntax, options, and other pertinent information appears on 
the screen. To exit, continue pressing the space bar until you see a 
command prompt, or press Q at any time to return immediately to your 
command prompt. The manuals often refer to information discussed in 
another guide in the suite. The format for this type of cross reference is 
"Chapter Title," Name of Guide. For a complete description of A/UX 
guides, see Road Map to A/UX Documentation. This guide contains 
descriptions of each A/UX guide, the part numbers, and the ordering 
information for all the guides in the A/UX documentation suite. 
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Introduction 
to the A/UX Reference Manuals 

1 . How to use the reference manuals 

A/UX Command Reference, A/UX Programmer's Reference, and A/UX 
System Administrator' s Reference are reference manuals for all the pro- 
grams, utilities, and standard file formats included with your A/UX® 
system. 

The reference manuals constitute a compact encyclopedia of A/UX 
information. They are not intended to be tutorials or learning guides. 
If you are new to A/UX or are unfamiliar with a specific functional 
area (such as the shells or the text formatting programs), you should 
first read A/UX Essentials and the other A/UX user guides. After you 
have worked with A/UX, the reference manuals help you understand 
new features or refresh your memory about command features you 
already know. 

2. Information contained in the reference manuals 

A/UX reference manuals are divided into three volumes: 

• The two-part A/UX Command Reference contains information 
for the general user. It describes commands you type at the 
A/UX prompt that list your files, compile programs, format text, 
change your shell, and so on. It also includes programs used in 
scripts and command language procedures. The commands in 
this manual generally reside in the directories /bin, 
/usr/binand /usr/ucb. 

• The two-part A/UX Programmer's Reference contains informa- 
tion for the programmer. It describes utilities for programming, 
such as system calls, file formats of subroutines, and miscellane- 
ous programming facilities. 

• A/UX System Administrator's Reference contains information for 
the system administrator. It describes commands you type at the 
A/UX prompt to control your machine, such as accounting 
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commands, backing up your system, and charting your system's 
activity. These commands generally reside in the directories 
/etc, /usr/etc,and /usr/lib. 

These areas can overlap. For example, if you are the only person using 
your machine, then you are both the general user and the system 
administrator. 

To help direct you to the correct manual, you may refer to A/UX Refer- 
ence Summary and Index, which is a separate volume. This manual 
summarizes information contained in the other A/UX reference manu- 
als. The three parts of this manual are a classification of commands by 
function, a listing of command synopses, and an index. 

3. How the reference manuals are organized 

All manual pages are grouped by section. The sections are grouped by 
general function and are numbered according to standard conventions 
as follows: 



1 


User commands 


1M 


System maintenance commands 


2 


System calls 


3 


Subroutines 


4 


File formats 


5 


Miscellaneous facilities 


6 


Games 



7 Drivers and interfaces for devices 

8 A/UX Startup shell commands 

Manual pages are collated alphabetically by the primary name associ- 
ated with each. For the individual sections, a table of contents is pro- 
vided to show the sequence of manual pages. A notable exception to 
the alphabetical sequence of manual pages is the first entry at the start 
of each section. As a representative example, intro. 1 appears at 
the start of Section 1. These intro . section-number manual pages 
are brought to the front of each section because they introduce the 
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other man pages in the same section, rather than describe a command 
or similar provision of A/UX. 

Each of the reference manuals includes at least one complete section of 
man pages. For example, the A/UX Command Reference contains sec- 
tions 1 and 6. However, since Section 1 (User Commands) is so large, 
this manual is divided into two volumes, the first containing Section 1 
commands that begin with letters A through L, and the second contain- 
ing Section 6 commands and Section 1 commands that begin with 
letters M through Z. The sections included in each volume are as fol- 
lows. 



A/UX Command Reference contains sections 1 and 6. Note that both of 
these sections describe commands and programs available to the gen- 
eral user. 

• Section 1 — User Commands 

The commands in Section 1 may also belong to a special 
category. Where applicable, these categories are indicated by the 
letter designation that follows the section number. For example, 
the N in ypcat(lN) indicates networking as described follow- 
ing. 

1C Communications commands, such as cu and 

tip. 

1G Graphics commands, such as graph and 
tplot. 

IN Networking commands, such as those which help 
support various networking subsystems, including 
the Network File System (NFS), Remote Process 
Control (RPC), and Internet subsystem. 

• Section 6 — User Commands 

This section contains all the games, such as cribbage and 
worms. 
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A/UX Programmer' s Reference contains sections 2 through 5. 

• Section 2 — System Calls 

This section describes the services provided by the A/UX system 
kernel, including the C language interface. It includes two spe- 
cial categories. Where applicable, these categories are indicated 
by the letter designation that follows the section number. For 
example, the N in connect(2N) indicates networking as 
described following. 

2N Networking system calls 

2P POSIX system calls 

• Section 3 — Subroutines 

This section describes the available subroutines. The binary ver- 
sions are in the system libraries in the /lib and /usr/lib 
directories. The section includes six special categories. Where 
applicable, these categories are indicated by the letter designa- 
tion that follows the section number. For example, the N in 
mount (3N) indicates networking as described following. 

3C C and assembler library routines 

3F Fortran library routines 

3M Mathematical library routines 

3N Networking routines 

2P POSIX routines 

3S Standard I/O library routines 

3X Miscellaneous routines 

• Section A — File Formats 

This section describes the structure of some files, but does not 
include files that are used by only one command (such as the 
assembler's intermediate files). The C language struct 
declarations corresponding to these formats are in the 
/usr/include and /usr/include/sys directories. 
There is one special category in this section. Where applicable, 
these categories are indicated by the letter designation that fol- 
lows the section number. For example, the N in 
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protocols(4N) indicates networking as described following. 
4N Networking formats 

• Section 5 — Miscellaneous facilities 

This section contains various character sets, macro packages, and 
other miscellaneous formats. There are two special categories in 
this section. Where applicable, these categories are indicated by 
the letter designation that follows the section number. For exam- 
ple, the P in tcp(lP) indicates a protocol as described follow- 
ing, by the letter designation in parenthesis at the top of the 
page: 

5F Protocol families 

5P Protocol descriptions 

A/UX System Administrator' s Reference contains sections 1M, 7 and 8. 

• Section 1M — System Maintenance Commands 

This section contains system maintenance programs such as 

f sck and mkf s. 

• Section 7 — Drivers and Interfaces for Devices 

This section discusses the drivers and interfaces through which 
devices are normally accessed. While access to one or more disk 
devices is fairly transparent when you are working with files, the 
provision of device files permits you more explicit modes with 
which to access particular disks or disk partitions, as well as 
other types of devices such as tape drives and modems. For 
example, a tape device may be accessed in automatic-rewind 
mode through one or more of the device file names in the 
/dev/rmt directory (see tc(7)). The FILES sections of these 
manual pages identify all the device files supplied with the sys- 
tem as well as those that are automatically generated by certain 
A/UX configuration utilities. The names of the man pages gen- 
erally refer to device names or device driver names, rather than 
the names of the device files themselves. 

• Section 8 — A/UX Startup Shell Commands 

This section describes the commands that are available from 
within the A/UX Startup Shell, including detailed descriptions of 
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those that contribute to the boot process and those that help with 
the maintenance of file systems. 

4. How a manual entry is organized 

The name for a manual page entry normally appears twice, once in 
each upper corner of a page. Like dictionary guide words, these names 
appear at the top of every physical page. After each name is the sec- 
tion number and, if applicable, a category letter enclosed in 
parenthesis, such as (1) or (2N). 

Some entries describe several routines or commands. For example, 
chown and chgrp share a page with the name chown(l) at the 
upper corners. If you turn to the page chgrp(l), you find a reference 
to chown(l). (These cross-reference pages are only included in AIUX 
Command Reference and AIUX System Administrator' s Reference.) 

All of the entries have a common format, and may include any of the 
following parts: 

NAME 

is the name or names and a brief description. 

SYNOPSIS 

describes the syntax for using the command or routine. 

DESCRIPTION 

discusses what the program does. 

FLAG OPTIONS 

discusses the flag options. 

EXAMPLES 

gives an example or examples of usage. 

RETURN VALUE 

describes the value returned by a function. 

ERRORS 

describes the possible error conditions. 

FILES 

lists the filenames that are used by the program. 
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SEE ALSO 

provides pointers to related information. 

DIAGNOSTICS 

discusses the diagnostic messages that may be produced. Self- 
explanatory messages are not listed. 

WARNINGS 

points out potential pitfalls. 

BUGS 

gives known bugs and sometimes deficiencies. Occasionally, it 
describes the suggested fix. 

5. Locating information in the reference manuals 

The directory for the reference manuals, A/UX Reference Summary and 
Index, can help you locate information through its index and sum- 
maries. The tables of contents within each of the reference manuals 
can be used also. 

5.1 Table of contents 

Each reference manual contains an overall table of contents and indivi- 
dual section contents. The general table of contents lists the overall 
contents of each volume. The more detailed section contents lists the 
manual pages contained in each section and a brief description of their 
function. For the most part, entries appear in alphabetic order within 
each section. 

5.2 Commands by function 

This summary classifies the A/UX user and administration commands 
by the general, or most important function they perform. The complete 
descriptions of these commands are found in A/UX Command Refer- 
ence and A/UX System Administrator's Reference. Each is mentioned 
just once in this listing. 

The summary gives you a broader view of the commands that are avail- 
able and the context in which they are most often used. 
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5.3 Command synopses 

This section is a compact collection of syntax descriptions for all the 
commands in AIUX Command Reference and AIUX System 
Administrator's Reference. It may help you find the syntax of com- 
mands more quickly when the syntax is all you need. 

5.4 Index 

The index lists key terms associated with A/UX subroutines and com- 
mands. These key terms allow you to locate an entry when you don't 
know the command or subroutine name. 

The key terms were constructed by examining the meaning and usage 
of the A/UX manual pages. It is designed to be more discriminating 
and easier to use than the traditional permuted index, which lists nearly 
all words found in the manual page NAME sections. 

Most manual pages are indexed under more than one entry; for exam- 
ple, lorder(l) is included under "archive files," "sorting," and 
"cross-references." This way you are more likely to find the reference 
you are looking for on the first try. 

5.5 Online documentation 

Besides the paper documentation in the reference manuals, A/UX pro- 
vides several ways to search and read the contents of each reference 
from your A/UX system. 

To see a manual page displayed on your screen, enter the man(l) 
command followed by the name of the entry you want to see. For 
example, 

man passwd 

To see the description phrase from the NAME section of any manual 
page, enter the what is command followed by the name of the entry 
you want to see. For example, 

whatis apropos 
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To see a list of all manual pages whose descriptions contain a given 
keyword or string, enter the apropos command followed by the 
word or string. For example, 

apropos remove 

These online documentation commands are described more fully in the 
manual pages man(l), what is(l), and apropos(l) in A/UX Com- 
mand Reference. 
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s igi smember(3P) see s igs et ops(3P) 

s iglong jmp(3P) see s igset jmp(3P) 

sign(3F) Fortran transfer-of-sign intrinsic function 

signal(3) specify what to do upon receipt of a signal 

s igna 1(3F) specify Fortran action on receipt of a system signal 

s igprocma sk(3P) examine and change blocked signals 

s igset j mp(3P) non-local jumps 

s igsetops(3P) manipulate signal sets 

s igsu spend(3P) wait for a signal 

s in(3F) Fortran sine intrinsic function 

s in(3M) see t ri g(3M) 

s inh(3F) Fortran hyperbolic sine intrinsic function 

sinh(3M) hyperbolic functions 

sleep(3C) suspend execution for interval 

slot s(3X) ROM library functions 

sngl(3F) see ftype(3F) 

spray(3N) scatter data in order to check the network 

sprintf(3S) see print f(3S) 

sput 1(3X) access long integer data in a machine independent fashion 

sqrt(3F) Fortran square root intrinsic function 

sqrt(3M) see exp(3M) 

s rand(3C) see rand(3C) 

s rand(3F) see rand(3F) 

srand48(3C) see drand48(3C) 

s scanf (3S) see scanf (3S) 

s signal(3C) software signals 

s tore(3X) see dbm(3X) 

strcat(3C) see st ring(3C) 

st rchr(3C) see st ring(3C) 

s t r cmp(3C) see st r ing(3C) 

s t r cpy(3C) see st r ing(3C) 

strcspn(3C) see st ring(3C) 

s t r ing(3C) string operations 

st r len(3C) see st ring(3C) 

strncat(3C) see st ring(3C) 

s trncmp(3C) see st ring(3C) 

strncpy(3C) see st ring(3C) 

strpbrk(3C) see st ring(3C) 



iv Subroutines (M-Z) 



st rrchr(3C) see st r ing(3C) 

st r spn(3C) see s t r ing(3C) 

st rt od(3C) convert string to double-precision number 

strtok(3C) see string(3C) 

strtol(3C) convert string to integer 

swab(3C) swap bytes 

sy sconf (3P) get configurable system variables 

syst em(3F) issue a shell command from Fortran 

sy stem(3S) issue a shell command 

sy s_er rlist(3C) see per ror(3C) 

sy s_nerr(3C) see perror(3C) 

t an(3F) Fortran tangent intrinsic function 

tan(3M) see t r ig(3M) 

tanh(3F) Fortran hyperbolic tangent intrinsic function 

tanh(3M) see sinh(3M) 

t cdrain(3P) line control functions 

tcflow(3P) see tcdrain(3P) 

tcflush(3P) see tcdrain(3P) 

tcgetatt r(3P) get and set the terminal state 

tcgetpgrp(3P) get distinguished process group ID 

tcsendbreak(3P) see t cdrain(3P) 

t csetatt r(3P) see t cget att r(3P) 

tcsetpgrp(3P) set distinguished process group ID 

tdelet e(3C) see t search(3C) 

telldir(3) see di rect ory(3) 

telldir(3P) see directory(3P) 

tempnam(3S) see tmpnam(3S) 

termcap(3X) terminal independent operation routines 

tfind(3C) seetsearch(3C) 

tget ent(3X) see termcap(3X) 

tget f lag(3X) see termcap(3X) 

tgetnum(3X) see termcap(3X) 

tget st r(3X) see t ermcap(3X) 

tgot o(3X) see termcap(3X) 

tmpf ile(3S) create a temporary file 

tmpnam(3S) create a name for a temporary file 

toas ci i(3C) see conv(3C) 

tolower(3C) see conv(3C) 

t ouppe r(3C) see conv(3C) 

tput s(3X) see t ermcap(3X) 

t r ig(3M) trigonometric functions 

tsearch(3G) manage binary search trees 

ttyname(3C) find name of a terminal 
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ttyslot(3C) find the slot in the utmp file of the current user 

twalk(3C) see t sear ch(3C) 

tzset(3) seectime(3) 

tzsetwall(3) see ctime(3) 

umount(3) unmount a file system 

unget c(3S) push character back into input stream 

utmpname(3C) see getut(3C) 

var ar gs(3X) handle variable argument list 

vf print f (3S) see vprint f (3S) 

vprint f (3S) format and output data from a variable-length argument list 

vsprint f (3S) see vprint f(3S) 

xdr(3N) library routines for external data representation 

xor(3F) seebool(3F) 

yO(3M) seebessel(3M) 

yl(3M) seebessel(3M) 

yn(3M) see be s s el(3M) 

y pc In t (3N) yellow pages client interface 

yperr_s t r ing(3N) see ypclnt(3N) 

yppas swd(3N) update user password in yellow pages 

ypprot_err(3N) see ypclnt(3N) 

yp_all(3N) see ypclnt(3N) 

yp_bind(3N) see ypclnt(3N) 

yp_first(3N) see ypclnt(3N) 

yp_get_def ault_domain(3N) see ypclnt(3N) 

yp_mast er(3N) see ypclnt(3N) 

yp_match(3N) see ypclnt(3N) 

yp_next(3N) see ypclnt(3N) 

yp_orde r(3N) see ypclnt(3N) 

yp_unbind(3N) see ypclnt(3N) 

zabs(3F) seeabs(3F) 

z ip(3N) AppleTalk Zone Information Protocol (ZIP) interface 

zip_get localzones(3N) see zip(3N) 

zip_get my zone(3N) see zip(3N) 

z ip_get zoneli st(3N) see zip(3N) 

_tolower(3C) see conv(3C) 

t ouppe r(3C) see conv(3C) 
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NAME 

malloc, free, realloc, calloc, cfree — main 
memory allocator 

SYNOPSIS 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char * realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

void cfree (ptr , nelem , elsize ) 

char *ptr; 

unsigned nelem, elsize; 

DESCRIPTION 

malloc and free provide a simple general-purpose memory al- 
location package, malloc returns a pointer to a block of at least 
size bytes suitably aligned for any use. 

The argument to free is a pointer to a block previously allocated 
by malloc; after free is performed, this space is made avail- 
able for further allocation, but its contents are left undisturbed. 

Undefined results occur if the space assigned by malloc is over- 
run or if some random number is handed to free. 

malloc allocates the first contiguous reach of free space of 
sufficient size found in a circular search from the last block allo- 
cated or freed; it coalesces adjacent free blocks as it searches. It 
calls sbrk (see brk(2)) to get more memory from the system 
when there is no suitable space already free. 

realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. The 
contents are unchanged up to the lesser of the new and old sizes. 
If no free block of size bytes is available in the storage arena, 
realloc asks malloc to enlarge the arena by size bytes and 
then moves the data to the new space. 
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realloc also woiks if ptr points to a block freed since the last 
call of malloc, realloc, or calloc; thus sequences of free, 
malloc, and realloc can exploit the search strategy of mal- 
loc to do storage compaction. 

calloc allocates space for an array of nelem elements of size el- 
size. The space is initialized to zeros. 

The arguments to cf ree are the pointer to a block previously al- 
located by calloc plus the parameters to calloc. 

Each of the allocation routines returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of 
object 

RETURN VALUE 

malloc, realloc, and calloc return a NULL pointer if there 
is no available memory or if the arena is deteected to have been 
corrupted by storing outside the bounds of a block. When this 
happens the block pointed to by ptr may be destroyed. 

NOTES 

Search time increases when many objects have been allocated; 
that is, if a program allocates space but never frees it, each succes- 
sive allocation takes longer. 

SEE ALSO 

brk(2),malloc(3X). 
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NAME 

malloc, free, realloc, calloc, mallopt, 
mallinfo — fast main memory allocator 

SYNOPSIS 

♦include <malloc.h> 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char * realloc (ptr , size) 
char *ptr; 
unsigned size; 

char * calloc (nelem , elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfo (max) 
int max; 

DESCRIPTION 

malloc and free provide a simple general-purpose memory al- 
location package, which runs considerably faster than the 
malloc(3C) package. It is found in the library "malloc", and 
is loaded if the option "-lmalloc" is used with cc(l) or ld(l). 

malloc returns a pointer to a block of at least size bytes suitably 
aligned for any use. 

The argument to free is a pointer to a block previously allocated 
by malloc; after free is performed this space is made available 
for further allocation, and its contents have been destroyed (but 
see mallopt below for a way to change this behavior). 

Undefined results will occur if the space assigned by malloc is 
overrun or if some random number is handed to free. 

realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. The 
contents will be unchanged up to the lesser of the new and old 
sizes. 
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calloc allocates space for an array of nelem elements of size el- 
size. The space is initialized to zeros. 

ma 11 opt provides for control over the allocation algorithm. The 
available values for cmd are: 

M_MXFAST Set maxf ast to value. The algorithm allocates 
all blocks below the size of maxf ast in large 
groups and then doles them out very quickly. The 
default value for maxf ast is 0. 

M_NLBLKS Set numlblks to value. The above mentioned 
"large groups" each contain numlblks blocks. 
numlblks must be greater than 0. The default 
value for numlblks is 100. 

M_GRAIN Set grain to value. The sizes of all blocks 
smaller than maxf ast are considered to be 
rounded up to the nearest multiple of grain, 
grain must be greater than 0. The default value 
of grain is the smallest number of bytes which 
will allow alignment of any data type. Value will 
be rounded up to a multiple of the default when 
grain is set. 

m_keep Preserve data in a freed block until the next mal - 

loc, realloc, or calloc. This option is pro- 
vided only for compatibility with the old version 
of ma Hoc and is not recommended. 

These values are defined in the <malloc . h> header file. 

ma 11 opt may be called repeatedly, but may not be called after 
the first small block is allocated. 

mallinfo provides instrumentation describing space usage. It 
returns the structure: 



struct mallinfo 
int arena; 
int ordblks; 
int smblks; 
int hblkhd; 
int hblks; 
int usmblks; 
int fsmblks; 
int uordblks; 
int f ordblks; 



/* total space in arena */ 
/* number of ordinary blocks */ 
/* number of small blocks */ 
/* space in holding block headers */ 
/* number of holding blocks */ 
/* space in small blocks in use */ 
/* space in free small blocks */ 
/* space in ordinary blocks in use */ 
/* space in free ordinary blocks */ 
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int keepcost; /* space penalty if keep option */ 
/* is used */ 
} 

This structure is defined in the <malloc . h> header file. 

Each of the allocation routines returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of 
object. 

RETURN VALUE 

malloc, realloc and calloc return a NULL pointer if there 
is not enough available memory. When realloc returns NULL, 
the block pointed to by ptr is left intact. If mall opt is called 
after any allocation or if cmd or value are invalid, non-zero is re- 
turned. Otherwise, it returns zero. 

SEE ALSO 

brk(2), malloc(3C). 

WARNINGS 

This package usually uses more data space than malloc(3C). 
The code size is also bigger than malloc(3C). 
Note that unlike malloc(3Q, this package does not preserve the 
contents of a block when it is freed, unless the m_keep option of 
ma 11 opt is used. 

Undocumented features of malloc(3C) have not been duplicat- 
ed. 
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NAME 

matherr — error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception *x; 

DESCRIPTION 

matherr is invoked by functions in the Math Library when er- 
rors are detected. Users may define their own procedures for han- 
dling errors, by including a function named matherr in their 
programs, matherr must be of the form described above. When 
an error occurs, a pointer to the exception structure x will be 
passed to the user-supplied matherr function. This structure, 
which is defined in the <math . h> header file, is as follows: 

struct exception { 

int type; 

char *name; 

double argl; 

double arg2; 

double retval; 
}; 

The element type is an integer describing the type of error that has 
occurred, from the following list of constants (defined in the 
header file): 

domain argument domain error 

S I NG argument singularity 

overflow overflow range error 

underflow underflow range error 

T LO S S total loss of significance 

P LO S S partial loss of significance 

The element name points to a string containing the name of the 
function that incurred the error. The variables argl and argl are 
the arguments with which the function was invoked, retval is set 
to the default value that will be returned by the function unless the 
user's matherr sets it to a different value. 

If the user's matherr function returns nonzero, no error message 
will be printed, and errno will not be set 

If matherr is not supplied by the user, the default error-handling 
procedures, described with the math functions involved, will be 
invoked upon error. These procedures are also summarized in the 
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table below. In every case, errno is set to edom or erange and 
the program continues. 

EXAMPLES 

# include <math.h> 

int 

matherr (x) 

register struct exception *x; 

{ 

switch (x— >type) { 
case DOMAIN: 

/* change sqrt to return sqrt(-argl), not */ 
if ( ! strcmp (x— >name, "sqrt")) { 
x->retval = sqrt {-x->argl ) ; 

return (0); /* print message and set errno */ 
} 
case SING: 

/* all other domain or sing errors, 

print message and abort */ 
fprintf (stderr, "domain error in %s\n", x— >name) ; 
abort ( ) ; 
case PLOSS: 

/* print detailed error message */ 

fprintf (stderr, "loss of significance in %s(%g) = %g\n' 

x— >name, x->argl, x->retval); 
return (1); /* take no other action */ 



} 



return (0); /* all other errors, 

execute default procedure */ 
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DEFAULT ERROR HANDLING PROCEDURES 









Types < 


of Errors 






type 


DOMAIN 


SING 


OVERFLOW 


UNDERFLOW 


TLOSS 


PLOSS 


errno 


EDOM 


EDOM 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 
yO,yl,yn(arg£0) 


M.-H 


- 


- 


- 


M,0 


* 


EXP: 


- 


- 


H 





- 


- 


LOG.LOGIO: 
(arg<0) 
(arg = 0) 


M.-H 


M.-H 


- 


- 


- 


- 


POW: 

neg ** nonint 
** nonpos 


M,0 


- 


±H 





- 


- 


SQRT: 


M,0 


- 


- 


- 


- 


- 


GAMMA: 


- 


M,H 


H 


- 


- 


- 


HYPOT: 


- 


- 


H 


- 


- 


- 


SINH: 


- 


- 


±H 


- 


- 


- 


COSH: 


- 


- 


H 


- 


- 


- 


SIN, COS, TAN: 


- 


- 


- 


- 


M,0 


* 


ASIN.ACOS.ATAN2: 


M,0 


- 


- 


- 


- 


- 





ABBREVIATIONS 


* 


As much as possible of the value is returned. 


M 


Message is printed (EDOM error). 


H 


HUGE is returned. 


-H 


-HUGE is returned. 


±H 


HUGE or -HUGE is returned. 





is returned. 



February, 1990 
Revision C 



max(3F) max(3F) 



NAME 

max, maxO, amaxO, maxl, amaxl, dmaxl — Fortran 
maximum-value functions 

SYNOPSIS 

integer i, j, k, I 

real a, b, c, d 

double precision dpi, dpi, dp3 

l=max(i, j, k) 
c=max (a, b) 
flf=max {a, b, c) 
£=maxO (i, j) 
a=amaxO (i, j, k) 
z'=maxl (a, b) 
rf=amaxl (a, b, c) 
fl(p5=dmax 1 ( dpi , dp2 ) 

DESCRIPTION 

The maximum-value functions return the largest of their argu- 
ments; there may be any number of arguments, max is the generic 
form which can be used for all data types and takes its return type 
from that of its arguments. All arguments must be of the same 
type. maxO returns the integer form of the maximum value of its 
integer arguments; amaxO, the real form of its integer arguments; 
maxl, the integer form of its real arguments; amaxl, the real 
form of its real arguments; and dmaxl, the double-precision form 
of its double-precision arguments. 

SEE ALSO 

min(3F). 
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NAME 

mclock — return Fortran time accounting 

SYNOPSIS 

integer i 

i=mclock () 

DESCRIPTION 

mclock returns time accounting information about the current 
process and its child processes. The value returned is the sum of 
the current process's user time and the user and system times of 
all child processes. 

SEE ALSO 

times(2), clock(3C), system(3F). 
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NAME 

memccpy, memchr, memcmp, memcpy, memset — 
memory operations 

SYNOPSIS 

♦include <memory.h> 

char *memccpy (.s7, s2, c, n) 
char *sl, *s2; 
int c, n; 

char *memchr (s, c, n) 
char *s; 
int c r n; 

int memcmp ($7, s2, n) 
char *sl f *s2; 
int n; 

char *memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate efficiently on memory areas (arrays of 
characters bounded by a count, not terminated by a null charac- 
ter). They do not check for the overflow of any receiving memory 
area. 

memccpy copies characters from memory area s2 into si, stop- 
ping after the first occurrence of character c has been copied or 
after n characters have been copied, whichever comes first It re- 
turns either a pointer to the character after the copy of c in si or a 
NULL pointer if c was not found in the first n characters of s2. 

memchr returns either a pointer to the first occurrence of charac- 
ter c in the first n characters of memory area s or a NULL pointer 
if c does not occur. 

memcmp compares its arguments, looking at the first n characters 
only. It returns an integer less than, equal to, or greater than 0, 
depending on whether si is lexicographically less than, equal to, 
or greater than s2. 
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memcpy copies n characters from memory area s2 to si. It re- 
turns si. 

memset sets the first n characters in memory area s to the value 
of character c. It returns s. 

NOTES 

For user convenience, all these functions are declared in the op- 
tional <memory . h> header file. 

BUGS 

memcmp uses native character comparison. 

Because character movement is performed differently in different 
implementations, overlapping moves may yield unexpected 
results. 
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NAME 

min, minO, aminO, mini, aminl, dminl — Fortran 
minimum-value functions 

SYNOPSIS 

integer i, j, k, I 

real a, b, c, d 

double precision dpi, dp2, dp3 

/=min(i, j, k) 
c=min(a, b) 
d=min(a, b, c) 
&=minO (i, j) 
a=aminO {i, j, k) 
i=minl {a, b) 
d=aminl {a, b, c) 
o^5=dminl (dpi , dp2 ) 

DESCRIPTION 

The minimum-value functions return the minimum of their argu- 
ments. There may be any number of arguments, min is the gen- 
eric form which can be used for all data types. It takes its return 
type from that of its arguments, which must all be of the same 
type. minO returns the integer form of the minimum value of its 
integer arguments; aminO, the real form of its integer arguments; 
mini, the integer form of its real arguments; aminl, the real 
form of its real arguments; and dminl, the double-precision form 
of its double-precision arguments. 

SEE ALSO 

max(3F). 



February, 1990 

Revision C 



mkfifo(3P) mkfifo(3P) 



NAME 

mkf if o — make a FIFO special file 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/stat.h> 

int mkf if o (path, mode) 
char *path; 
mode_t mode; 

DESCRIPTION 

mkf if o creates a new FIFO special file named by the pathname 
pointed to by path. The mode of the new FIFO is initialized from 
mode. The file permission bits of mode are modified by the file 
creation mask of the process. If bits in mode other than file per- 
missions are set, the permissions on the FIFO will be undefined. 

For the POSIX environment, the following constants for mode are 
defined in <sys / st at .h> : 

S_I RUS R read permission , owner 

S_IWUSER writer permission, owner 

S_ixusr execute/search permission, owner 

S_I RGRP read permission , group 

S_IWGRP writer permission, group 

S_IXGRP execute/search permission, group 

S_l ROTH read permission, others 

S_IW0TH writer permission, others 

S_ixoth execute/search permission, others 

The owner ID of the FIFO is set to the effective user ID of the 
process. The group ID of the FIFO is set to the effective group ID 
of the process. 

On successful completion, mkf if o marks for update the 
st_atime, st_ctime, and st_mtime fields for the file. The 
st_ctime and st_mtime fields of the directory that contains 
the new entry are also marked for update. 

RETURN VALUE 

On successful completion, mkf if o returns a value of 0. Other- 
wise, a value of -1 is returned, no FIFO is created, and errno is 
set to indicate the error. 
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ERRORS 

mkf if o will fail and 
more of the following 

[ENAMETOOLONG] 



[ELOOP] 
[ENOTDIR] 
[ENOENT] 
[EROFS] 



[EEXIST] 
[EFAULT] 

SEE ALSO 

mknod(2), umask(2). 



the new FIFO will not be created if one or 
are true: 

A component of a pathname exceeded 
name_max characters, or an entire path- 
name exceeded path_max. 

Too many symbolic links were encoun- 
tered in translating a pathname. 

A component of the path prefix is not a 
directory. 

A component of the path prefix does not 
exist. 

The directory in which the FIFO is to be 
created is located on a read-only file sys- 
tem. 

The named FIFO exists. 

path points outside the allocated address 
space of the process. 
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NAME 

mktemp — make a unique filename 

SYNOPSIS 

char *mkt emp ( template ) 
char * template; 

DESCRIPTION 

The function mktemp alters the contents of the string referenced 
by * template so that it becomes a unique filename. The string at 
* template should be initialized to a filenamed with six trailing x 
characters; mktemp replaces the xs with a letter and the current 
process ID. The letter is selected so that the resulting name is not 
a duplicate an existing file. 

RETURN VALUE 

mktemp returns the address of the unique (altered) filename. If a 
unique name cannot be created, template will point to a null 
(empty) string. 

SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 

BUGS 

It is possible to run out of letters. 
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NAME 

mod, amod, dmod — Fortran remaindering intrinsic functions 

SYNOPSIS 

integer /, j, k 
real rl , r2, r3 
double precision dpi, dp2, dp3 

k=mod(i, j) 

r3=amod(ri, r2) 
r3=mod(rl, r2) 

dp3 =dmo d ( dpi , dp2 ) 
dp3=mod ( dpi , dp2 ) 

DESCRIPTION 

mod returns the integer remainder of its first argument divided by 
its second argument, amod and dmod return, respectively, the 
real and double-precision whole number remainder of the integer 
division of their two arguments. The generic version mod returns 
the data type of its arguments. 
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NAME 

monitor — prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor {lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc) () , (*highpc) () ; 
WORD *buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc -p automatically includes 
calls for monitor with default parameters; monitor needn't be 
called explicitly except to gain fine control over profiling. 

monitor is an interface to prof il(2). lowpc and highpc are 
the addresses of two functions; buffer is the address of a (user sup- 
plied) array of bufsize elements of type WORD (defined in the 
<mon . h> header file), monitor arranges to record a histogram 
in the buffer. This histogram shows periodically sampled values 
of the program counter and counts of calls of certain functions. 
The lowest address sampled is that of lowpc, the highest address is 
just below highpc. lowpc may not equal for this use of moni- 
tor, nfunc is the maximum number of call counts that can be 
kept; only calls of functions compiled with the profiling option -p 
of cc(l) are recorded. (The C Library and Math Library supplied 
when cc -p is used also have call counts recorded.) For the 
results to be significant, especially where there are small, heavily 
used routines, it is suggested that the buffer be no more than a few 
times smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use: 

extern etext; 

monitor ((int (*)())2, etext, buf, bufsize, nfunc); 

etext lies just above all the program text; see end(3C). 

To stop execution monitoring and write the results on the file 
mon.out,use 

monitor ((int (*)())0, 0, 0, 0, 0) ; 

prof (1) can then be used to examine the results. 
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FILES 

mon . out 

/lib/libp/libc.a 

/lib/libp/libm.a 

SEE ALSO 

cc(l), prof(l), profil(2), end(3C). 
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NAME 

mount — mount a file system 

SYNOPSIS 

int mount (spec, dir, rwflag) 
char *spec, *dir; 
int rwflag; 

DESCRIPTION 

mount requests that a removable file system contained on the 
block special file identified by spec be mounted on the directory 
identified by dir. spec and dir are pointers to path names. 

Upon successful completion, references to the file dir will refer to 
the root directory on the mounted file system. 

The low-order bit of rwflag is used to control write permission on 
the mounted file system; if 1, writing is forbidden, otherwise writ- 
ing is permitted according to individual file accessibility. Physi- 
cally write-protected and magnetic tape file systems must be 
mounted read-only or errors will occur when access times are up- 
dated, whether or not any explicit write is attempted. 

mount may be invoked only by the superuser. 

ERRORS 

mount will fail if one or more of the following are true: 



[EPERM] 

[ENOENT] 

[ENOTDIR] 

[ENOTBLK] 
[ENXIO] 

[ENOTDIR] 
[EFAULT] 

[EBUSY] 
[EPERM] 



The effective user ID is not superuser. 

Any of the named files does not exist. 

A component of a path prefix is not a 
directory. 

spec is not a block special device. 

The device associated with spec does not 
exist. 

dir is not a directory. 

spec or dir points outside the allocated 
address space of the process. 

dir is currently mounted on, is someone's 
current working directory, or is otherwise 
busy. 

A pathname contains a character with the 
high-order bit set. 
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[ENAMETOOLONG] 



[ELOOP] 



[EBUSY] 



A component of a pathname exceeded 
name_max characters, or an entire path- 
name exceeded path_max. 

Too many symbolic links were encoun- 
tered in translating a pathname. 

The device associated with spec is 
currently mounted. 

There are no more mount table entries. 



[EBUSY] 

RETURN VALUE 

Upon successful completion a value of is returned. Otherwise, a 
value of -1 is returned and errno is set to indicate the error. 

SEE ALSO 

f smount(2), unmount(2), umount(3), f stab(4). 



February, 1990 

Revision C 



mount (3N) mount (3N) 



NAME 

mount — keep track of remotely mounted file systems 

SYNOPSIS 

♦include <rpcsvc/mount .h> 

DESCRIPTION 
RPCINFO 

Program number: MOUNTPROG 

xdr routines: 

xdr_exportbody (xdrs, ex) 

XDR *xdrs; 

struct exports *ex; 
xdr_exports (xdrs, ex) ; 

XDR *xdrs; 

struct exports **ex; 
xdr_fhandle (xdrs, fh) ; 

XDR * xdrs 7 

fhandle_t *fp; 
xdr_f hstatus (xdrs, fhs) / 

XDR *xdrs; 

struct fhstatus *fhs; 
xdr_groups (xdrs, gr) ; 

XDR *xdrs; 

struct groups *gr; 
xdrjmountbody (xdrs, ml) 

XDR *xdrs; 

struct mountlist *ml; 
xdr_mountlist (xdrs, ml) ; 

XDR *xdrs; 

struct mountlist **ml; 
xdr_j>ath (xdrs, path); 

XDR *xdrs; 

char **path; 

Procs: 

MOUNTPROC_MNT 

Argument of xdr_path; returns fhstatus. Requires 
UNIX authentication. 

MOUNTPROC_DUMP 

No arguments; returns structure mountlist. 
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MOUNTPROC_UMNT 

Argument of xdrjpath; no results. Requires UNIX au- 
thentication. 

MOUNTPROC_UMNTALL 

No arguments; no results. Requires UNIX authentication. 
Unmounts all remote mounts of sender. 

MOUNTPROC_EXPORT 
MOUNTPROC_EXPORTALL 

No arguments; returns structure exports. 
Versions: mountvers_ORIG 
Structures: 

struct mountlist { /* what is mounted */ 
char *ml_name; 
char *ml_path; 
struct mountlist *ml_nxt; 

}; 

struct fhstatus { 
int fhs_status; 
fhandle_t fhs_fh; 

>; 

/* 

* List of exported directories 

* An export entry with ex_groups NULL 

* indicates an entry which is exported 

* to the world. 
*/ 

struct exports { 

dev_t ex_dev; /* dev of directory */ 
char *ex_name; /* name of directory */ 
struct groups *ex_groups; 
/* groups allowed to mount this entry */ 
struct exports *ex_next; 

}; 

struct groups { 

char *g_name; 

struct groups *g_next; 
}; 

SEE ALSO 

mount(lM), mountd(lM), showmount(lM). NFS Protocol 
Spec, Section 3, in AIUX Network Applications Programming. 
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NAME 

nbp_j?arse_entity, nbp_make_entity, 
nbp_confirm, nbp_lookup, nbp_register, 
nbp_remove — ApplcTalk Name Binding Protocol (NBP) 
interface. 

SYNOPSIS 

#include <at/appletalk.h> 
#include <at/nbp.h> 
cc [flags] files -lat [libraries] 

int nbp_parse_entity (entity, str) ; 
at_entity_t * entity; 
char *str; 

int nbp_make_entity {entity, object, type, zone) ; 
at_entity_t *entity; 
char *object, *type, *zone; 

int nbp__confirm(c/irfry, dest, retry); 
at_entity_t * entity; 
at_inet_t *dest; 
at_retry_t * retry; 

int nbp_lookup (entity, buf, max, retry) ; 
at_entity_t * entity; 
at_nbptuple_t *buf; 
int max; 
at_retry_t * retry; 

int nbp_register (entity, fd, retry) ; 
at_entity_t ^entity; 
int fd; 
at_retry_t *retry; 

int nbp_remove (entity, fd ) ; 
at_entity_t * entity; 
int fd; 

DESCRIPTION 

The NBP interface provides applications with access to the NBP 
operations. The routines use these structures (defined in 
<at/appletalk.h>): 

typedef struct at_inet { 
at_net net ; 
at node node ; 
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at_socket socket; 
} at_inet_t; 

typedef struct at_retry { 

short interval; 

short retries; 

u_char backoff; 
} at_retry_t; 

The AppleTalk NBP operations also use these structures (defined 
in <at/nbp.h>): 

typedef struct at_nvestr { 

char len; 

char str[NBP_NVE_STR_SIZE] ; 
} at_nvestr_t; 

typedef struct at_entity { 

at_nvestr_t object; 

at_nvestr_t type; 

at_nvestr_t zone; 
} at_entity_t; 

typedef struct at_nbptuple { 

at_inet_t enu_addr; 

u_char enu_enum; 

at_entity_t enu_entity; 
} at_nbptuple_t; 

The at_inet_t structure specifies the AppleTalk internet ad- 
dress of a DDP socket endpoinL 

The at_retry_t structure specifies the retry interval and max- 
imum count for a transaction. The members of this structure are 

interval The interval in seconds before NBP retries a request. 

retries The maximum number of retries for this NBP request 

backoff Not used by NBP. 

The at_nvestr_t structure specifies an NBP entity string. The 
members of this structure are: 

len The length of the string in bytes. 
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str The character data for this string. 

The at_entity_t structure describes an entity name, which 
consists of three NBP entity strings: object, type, and zone. 

All NBP routines work with the at_entity_t structure. Two 
utility routines, nbp_parse_entity, and 

nbp_mak:e_entity, are provided to aid in creating 
at_entity_t structures from C strings. 

The nbp_j»arse_entity structure constructs an NBP entity 
name from a NULL-terminated C string of the form object, 
objecf.type, or object:type@zone. The entity name is placed in the 
at_entity_t structure entity. This routine returns on success. 

The nbp_make_entity structure constructs an NBP entity 
name from object, type, and zone strings. The strings are NULL- 
terminated C strings. The entity name is placed into the 
at_entity_t structure entity. Use the object, type, and zone 
character strings to construct the entity name. This routine returns 
on success. 

The nbp_conf irm structure sends a confirmation request to the 
specified node to see if an entity name is still registered at the 
specified AppleTalk internet address. 

entity A pointer to the at_entity_t structure containing 

the entity name. No wildcards are allowed in the enti- 
ty name strings, but an asterisk (*) for zone is accept- 
able. 

dest The AppleTalk internet address to confirm. If the 

name is still registered on the node but at a different 
socket number, the socket number in dest is updated. 

retry A pointer to the structure that specifies the NBP re- 

quest retry interval in seconds and the maximum retry 
count. If retry is NULL, the system uses the default 
values: a 1 -second interval and eight retries. 

On success, nbp_confirm returns 1. It returns when the 
name is not confirmed, and -1 on error. 

The nbp_lookup structure returns a list of registered name- 
address pairs via an NBP lookup. The parameters are 

entity A pointer to the at_entity_t structure containing 

the entity name to be looked up. 



February, 1990 

Revision C 



nbp(3N) nbp(3N) 



buf An array of at_nbptuple_t to receive entity tu- 

ples. 

max The maximum number of entity tuples to accept If 

max or more distinct tuples are received before the 
lookup retry is exceeded, the lookup terminates. 

retry The pointer to the structure that specifies the NBP re- 

quest retry interval in seconds and the maximum retry 
count If retry is NULL, the system uses the default 
values: a one-second interval and eight retries. 

On success, nbp_lookup returns the number of entity tuples ac- 
tually received. 

The nbp_register structure adds the specified name-socket 
pair to the list of registered names on this node. The parameters 
are 

entity A pointer to the at_entity_t structure containing 

the entity name to be registered. The zone field of en- 
tity is always ignored. No wildcards are allowed in 
the entity strings. 

fd An AppleTalk file descriptor to be registered with the 

given name. 

retry A pointer to the structure that specifies the NBP re- 

quest retry interval in seconds and the maximum retry 
count If retry is NULL, the system uses the default 
values: a 1 -second interval and eight retries. 

The nbp_remove structure removes the specified entity name 
from the list of registered names on this node. The parameters are 

entity A pointer to the at_entity_t structure containing 

the entity name to be removed. The zone field of enti- 
ty is always ignored. No wildcards are allowed in the 
entity strings. 

fd The AppleTalk file descriptor that is registered with 

the given name. 

WARNINGS 

Strings in entity names and entity tuples are not NULL terminated. 

All characters in NVE names are significant, including trailing 
blanks. 
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See Inside AppleTalk for a description of NVE names. 

DIAGNOSTICS 

All routines return -1 on error with a detailed error code in errno: 

[ E I nval ] The entity name is invalid. 

[ ET IMEDOUT ] The request exceeded maximum retry count. 

SEE ALSO 

ddp ( 3n) , Inside AppleTalk. 
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NAME 

nl i s t — get entries from name list 

SYNOPSIS 

♦include <a.out.h> 

int nlist {filename, nl) 
char * filename; 
struct nlist *nl; 

DESCRIPTION 

nlist examines the name list in the executable file whose name 
is pointed to by filename; it selectively extracts a list of values and 
puts them in the array of nlist structures pointed to by nl. The 
name list nl consists of an array of structures containing names of 
variables, types, and values. The list is terminated with a null 
name; i.e., a null string is in the name position of the structure. 
Each variable name is looked up in the name list of the file. If the 
name is found, the type and value of the name are inserted in the 
next two fields. The type filed will be set to unless the file was 
compiled with the -g option. If the name is not found, both en- 
tries are set to 0. See a . out(4) for a discussion of the symbol 
table structure. 

This function is useful for examining the system name list kept in 
the file /unix. In this way programs can obtain system addresses 
that are up to date. 

RETURN VALUE 

nlist returns -1 upon error, otherwise it returns 0. 

All value entries are set to if the file cannot be read or if it does 
not contain a valid name list 

SEE ALSO 

a . out (4). 
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NAME 

paps_open, paps_get_next_job, paps_status, 
paps_close, pap_open, pap_read, 
pap_read_ignore, pap_status, pap_write, 
pap_close — AppleTalk Printer Access Protocol (PAP) 
interface 

SYNOPSIS 

♦include <at/appletalk.h> 
♦include <at/pap.h> 
♦include <at/nbp.h> 
cc \flags] files -lat [libraries] 

int paps_open ( ) 

int paps_get_next_job (fd) 
int fd; 

int paps_status {fd, status) 
int fd; 
char *status; 

int paps_close (fd) 
int fd; 

int pap_open {tuple) 
at_nbptuple_t * tuple; 

int pap_read {fd, data, len) 
int fd, len; 
char *data; 

int pap_read_ignore {fd) 
int fd; 

char *pap_status (tuple) 
at_nbptuple_t *tuple; 

int pap_write (fd, data, len, eof, flush) 
int fd, len; 
int eof, flush; 
char *data; 

int pap_close (fd) 
int /<i; 
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DESCRIPTION 

The PAP interface provides applications with access to the Ap- 
pleTalk Printer Access Protocol operations. The interface routines 
can be divided into two sets: One set provides services for a PAP 
client, the other for a PAP server. The routines for the PAP server 
are 



paps_open 

pap_read 

paps_get_next_job 

paps_status 

paps_close 

The routines for the PAP client are: 



pap_open 

pap_read 

pap_read_igno re 

pap_status 

pap_write 

pap_close 

The paps_open routine opens a PAP server AppleTalk file 
descriptor for a PAP server. The caller may then use 
nbp_register (see nbp(3N)) to register a network- visible en- 
tity (NYE) on the socket and paps_status to post a status 
string on it The paps_open routine returns an AppleTalk file 
descriptor on success, -1 on failure. 

The paps_get_next_job routine is called by a server when it 
is ready to respond to a new PAP client. It returns a PAP server 
AppleTalk file descriptor that is set up for PAP reading from the 
client that has been waiting the longest. The parameter is 

fd A PAP server AppleTalk file descriptor from a previ- 

ous paps_open. 

Upon successful completion a PAP server AppleTalk file descrip- 
tor is returned. 

The paps_status routine changes the status string associat- 
ed with an open PAP server AppleTalk file descriptor. This is the 
string returned to a PAP client from a pap_status call. The 
parameters are 
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fd An open PAP server AppleTalk file descriptor re- 

turned from a paps_open call. 

status A pointer to a null-terminated character string con- 

taining the status string being posted. Strings 
longer than 255 characters are truncated. 

Upon successful completion a value of is returned. 

The paps_close routine closes an open PAP server file descrip- 
tor. The parameter is 

fd The file descriptor to be closed. 

It returns upon successful completion. 

The pap_open routine opens a PAP client file descriptor to a 
server. It attempts to connect to the server whose name and ad- 
dress are contained in the tuple parameter. The command 
nbp_lookup (see nbp(3N)) may be used to obtain a valid name 
and address for the desired PAP server. 

Upon successful completion, this routine returns a PAP client file 
descriptor connected to the server requested. 

The pap_read routine reads data from a server PAP file descrip- 
tor opened by a paps_open, followed by a 
paps_get_next_job call. The parameters are 

fd A PAP server file descriptor. 

data A pointer to the buffer containing the data to be re- 

turned. The maximum data length specified by the 
length parameter is 512 bytes. 

length The maximum length to be read. 

Upon successful completion, the number of bytes read is returned. 
A value of is returned when an end-of-file is reached. 

The pap_read_ignore routine issues a PAP read request and 
ignores any returned data. This is used to allow LaserWriters to 
function when they want to return status messages. The parameter 
is 

fd A PAP client file descriptor returned by an earlier 

pap_open . 

The pap_status routine locates a PAP server and returns a 
pointer to its status string. The parameter is 
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tuple A pointer to a tuple structure containing the name and 

address of a PAP server entity. The routine 
nbp_lookup (See nbp(3N)) may be used to get a 
valid tuple. 

Upon successful completion, a pointer to the string containing the 
PAP server's status is returned. If the printer's status cannot be 
recovered, NULL is returned. 

The pap_write routine sends the data passed to it to the other 
end of a PAP server session. The parameters are 

fd A PAP client AppleTalk file descriptor. 

data A pointer to the data being written. 

len The length of the data being written; this must not 

exceed 5 12 bytes. 

eof A Boolean flag indicating whethere EOF indication is to 

be sent to the other end of the PAP session (after the 
data has been sent) to indicate that no more data will be 
sent Setting eof to true also implies flush. 

flush A Boolean flag indicating whether data for all waiting 
PAP writes is to be sent to the remote end. Because 
PAP runs on top of ATP, PAP writes are queued until 
either a complete ATP response is available (about 4 
KB) or an end-of-message is sent This call sends an 
ATP end-of-message, which causes all waiting PAP 
writes to be sent to the other end. This should be done if 
a higher level protocol (for example, a handshake with a 
LaserWriter) needs to do a write followed by a read. 

Upon successful completion, a value of is returned. 

The pap_close routine closes an open PAP client file descrip- 
tor. The parameter is 

fd The file descriptor to be closed. 

It returns upon successful completion. If the file descriptor is no 
longer open, it returns -1. 

ERRORS 

All routines except pap_status return -1 on error with a de- 
tailed error code in errno: 

[ E I nval ] An invalid argument was passed. 
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[ enetdown ] The network interface is down. 

[E shutdown] The PAP file descriptor has already been 
closed. 

[ etimedout ] The connection is timed out. 

See open(2), close(2), ioctl(2), read(2), and write(2) for 
additional error codes; see also errors returned by the underlying 
NBP, ATP, and DDP modules. 

SEE ALSO 

atp(3N), ddp(3N), nbp(3N), rtmp(3N), Inside AppleTalk. 
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NAME 

pathconf, fpathconf — get configurable pathname 
variables 

SYNOPSIS 

♦include <unistd.h> 

long pathconf (path, name) 
char *path; 
int name; 

long fpathconf (fildes, name) 
int fildes, name; 

DESCRIPTION 

pathconf and fpathconf provide a method for an application 
to determine the current value of a configurable limit or option 
that is associated with a file or directory. 

For fpathconf, path points to a pathname of a file or directory. 
For fpathconf, fildes is an open file descriptor, name is the 
variable to be queried relative to the file or directory. The follow- 
ing variables can be queried: 

_PC_LINK_MAX 

_PC_MAX_CANON 

_PC_MAX_INPUT 

_PC_NAME_MAX 

_PC_PATH_MAX 

_PC_PIPE_BUF 

_PC_CHOWN_RE S TRI CTED 

_P C_CHOWN_S UP_GRP 

_PC_DIR_DOTS 

_PC_GROUP_PARENT 

_PC_LINK_DIR 

_PC_NO_TRUNC 

_PC_UTIME_OWNER 

_PC_VDI SABLE 

RETURN VALUE 

If the named variable is not defined on the system, or if name is 
not a valid variable name, or if the variable cannot be associated 
with the specified file or directory, or if the process does not have 
permission to query the file specified by path, or if path does not 
exist, pathconf returns -1. 



February, 1990 

Revision C 



pathconf(3P) 



pathconf(3P) 



If the named variable is not defined on the system, or if name is 
not a valid variable name, or if the variable cannot be associated 
with the specified file or directory, f pathconf returns -1. 

If none of the above are true, pathconf and f pathconf return 
the current value associated with the variable for the file or direc- 
tory. 

ERRORS 

pathconf and f pathconf will fail if one or more of the fol- 
lowing are true: 

A component of the path prefix is not a 
directory. 

A component of a pathname exceeded 
name_max characters, or an entire path- 
name exceeded path_max. 

Too many symbolic links were encoun- 
tered in translating a pathname. 

The named file does not exist. 

Search permission is denied for a com- 
ponent of the path prefix. 

path points to an invalid address. 

The value of the name is invalid, or the 
variable name is not associated with the 
specified file. 

f pathconf will also fail if the following condition occurs: 

[ ebadf ] The open file descriptor, fildes, is not valid. 

SEE ALSO 

sysconf(3P). 



[ENOTDIR] 
[ENAMETOOLONG] 

[ELOOP] 

[ENOENT] 
[EACCES] 

[EFAULT] 
[EINVAL] 
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NAME 

perror, errno, sys_errlist, sys_nerr — system 
error messages 

SYNOPSIS 

void perror (5) 
char *j; 

extern int errno; 

extern char *sys_errlist [] ; 

extern int sys_nerr; 

DESCRIPTION 

perror produces a message on the standard error output, 
describing the last error encountered during a call to a system or 
library function. The argument string s is printed first, then a 
colon and a blank, then the message and a newline. To be of most 
use, the argument string should include the name of the program 
that incurred the error. The error number is taken from the exter- 
nal variable errno, which is set when errors occur but not 
cleared when nonerroneous calls are made. 

To simplify variant formatting of messages, the array of message 
strings sys_errlist is provided; errno can be used as an in- 
dex in this table to get the message string without the newline. 
sys_nerr is the largest message number provided for in the 
table; it should be checked because new error codes may be added 
to the system before they are added to the table. 

SEE ALSO 

intro(2). 
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NAME 

plot — graphics interface subroutines 

SYNOPSIS 

int openpl ( ) 

int erase () 

int label (s) 
char *s; 

int lineUi, yl, x2, y2) 
int xl, yl, x2, y2; 

int circle (x, y, r) 
int x, y, r; 

int arc U, y, xO, yO, xl , yl) 
int x, y t xO, yO, xl , yl; 

int move (x, y) 
int x, y; 

int cont (x, y) 
int x, y; 

int point (x, y) 
int x f y; 

int linemod(s) 
char *s; 

int space (xO, yO, xl , yl) 
int xO, yO, xl , yl; 

int closeplO 

DESCRIPTION 

These subroutines generate graphic output in a relatively device- 
independent manner, space must be used before any of these 
functions to declare the amount of space necessary; see plot(4). 
openpl must be used before any of the others to open the device 
for writing, closepl flushes the output. 

ci rcle draws a circle of radius r with center at the point (x,y). 

arc draws an arc of a circle with center at the point (x,y) between 
the points (xO,yO) and (xl,yl). 

String arguments to label and linemod are terminated by nulls 
and do not contain newlines. 
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See plot(4) for a description of the effect of the remaining func- 
tions. 

The library files listed below provide several variations of these 
routines. 

FILES 

/usr/lib/libplot .a produces output for tplot(lG) 

filters 

/usr/lib/lib300.a forDASI300 

/usr/lib/lib300s.a for DASI 300s 

/usr/lib/lib450.a for DASI 450 

/usr/lib/lib4014.a for Tektronix 4014 

WARNINGS 

To compile a program containing these functions in file . c, use 

cc file.c -lplot 

To execute it, use 

a. out | tplo 

The above routines use <stdio . h>. Therefore, the size of pro- 
grams not otherwise using standard I/O is increased more than 
might be expected. 

SEE ALSO 

tplot(lG), plot(4). 
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NAME 

popen, pclose — initiate pipe to/from a process 

SYNOPSIS 

#include <stdio.h> 

FILE * popen (command, type) 
char * command, *type; 

int pclose (stream) 
FILE * stream; 

DESCRIPTION 

The arguments to popen are pointers to null-terminated strings; 
one string contains a shell command line and the other contains an 
I/O mode. The mode may he either "r" for reading or "w" for 
writing, popen creates a pipe between the calling program and 
the command to be executed. The value returned is a stream 
pointer. If the I/O mode is w, one can write to the standard input 
of the command by writing to the file stream; if the I/O mode is r, 
one can read from the standard output of the command, by reading 
from the file stream. 

A stream opened by popen should be closed by pclose, which 
waits for the associated process to terminate and returns the exit 
status of the command. 

Because open files are shared, a type "r" command may be used 
as an input filter and a type "w" as an output filter. 

RETURN VALUE 

popen returns a NULL pointer if files or processes cannot be 
created. 

pclose returns -1 if stream is not associated with a command 
opened by popen. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). 

BUGS 

If the original processes and processes opened by popen con- 
currently read or write a common file, neither should use buffered 
I/O, because the buffering gets all mixed up. Problems with an 
output filter may be forestalled by careful buffer flushing, for ex- 
ample, by using f flush (see f close(3S)). 
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If an illegal type is passed, popen will fork and exec the com- 
mand line passed to it before it discovers that the type was illegal. 
This will result in a NULL pointer being returned and a broken 
pipe (with the command executing in the background). 
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NAME 

printf, fprintf, sprintf — format and output string and 
numeric data 

SYNOPSIS 

♦include <stdio.h> 

int printf {format[, arg]. . .) 
char * format; 

int fprintf (stream, format[, arg]. . .) 
FILE * stream; 
char * format; 

int sprintf ( s, format[, arg]. ..) 
char *s, format; 

DESCRIPTION 

printf places output on the standard output stream stdout. 
fprintf places output on the named output stream, sprintf 
places output, followed by the null character (\0) in consecutive 
bytes starting at *s\ it is the user's responsibility to ensure that 
enough storage is available. 

Each of these functions converts, formats, and prints its args 
under control of the format. The format is a character string that 
contains two types of objects: plain characters, which are simply 
copied to the output stream, and conversion specifications, each of 
which results in fetching zero or more args. The results are 
undefined if there are insufficient args for the format. If the for- 
mat is exhausted while args remain, the excess args are simply ig- 
nored. 

Each conversion specification is introduced by the character %. 
After the %, the following appear in sequence: 

Zero or more flags, which modify the meaning of the conver- 
sion specification. 

An optional decimal digit string specifying a minimum field 
width. If the converted value has fewer characters than the 
field width, it will be padded to the field width on the left (de- 
fault) or right (if the left-adjustment flag - has been given); 
see below for flag specification. If the field width for an s 
conversion is preceded by a 0, the string is right adjusted 
with zero padding on the left. 
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A precision that gives the minimum number of digits to ap- 
pear for the d, o, u, x, or x conversions, the number of digits 
to appear after the decimal point for the e and f conversions, 
the maximum number of significant digits for the g conver- 
sion, or the maximum number of characters to be printed 
from a string in the s conversion. The format of the preci- 
sion is a period ( . ) followed by a decimal digit string; a null 
digit string is treated as zero. 

An optional 1 (ell) specifying that a following d, o, u, x, or 
X conversion character applies to a long integer arg. An 1 
before any other conversion character is ignored. 

A character that indicates the type of conversion to be ap- 
plied. 

A field width or precision may be indicated by an asterisk (*) in- 
stead of a digit string. In this case, an integer arg supplies the 
field width or precision. The arg that is actually converted is not 
fetched until the conversion letter is seen; therefore, the args 
specifying field width or precision must appear before the arg (if 
any) to be converted. 

The flag characters and their meanings are: 

The result of the conversion will be left-justified 
within the field. 

+ The result of a signed conversion will always begin 

with a sign (+ or -). 

blank If the first character of a signed conversion is not a 

sign, a blank will be prefixed to the result This im- 
plies that if the blank and + flags both appear, the 
blank flag will be ignored. 

# This flag specifies that the value is to be converted to 

an "alternate form." For c, d, s, and u conversions, 
the flag has no effect. For o conversion, it increases 
the precision to force the first digit of the result to be 
a zero. For x (x) conversion, a non-zero result will 
have Ox (Ox) prefixed to it. For e, E, f , g, and G 
conversions, the result will always contain a decimal 
point, even if no digits follow the point (normally, a 
decimal point appears in the result of these conver- 
sions only if a digit follows it). For g and G conver- 
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sions, trailing zeroes will not be removed from the 
result (which they normally are). 

The conversion characters and their meanings are: 

d,o,u,x,x The integer arg is converted to signed decimal, un- 
signed octal, decimal, or hexadecimal notation (x and 
X), respectively; the letters abcdef are used for x 
conversion and the letters abcdef for x conversion. 
The precision specifies the minimum number of digits 
to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with 
leading zeroes. (For compatibility with older ver- 
sions, padding with leading zeroes may alternatively 
be specified by prefixing a zero to the field width.) 
This does not imply an octal value for the field width. 
The default precision is 1. The result of converting a 
zero value with a precision of zero is a null string. 

f The float or double arg is converted to decimal nota- 

tion in the style [-]ddd.ddd, where the number of di- 
gits after the decimal point is equal to the precision 
specification. If the precision is missing, 6 digits are 
output; if the precision is explicitly 0, no decimal 
point appears. 

e,E The float or double arg is converted in the style [- 

]d.ddde±dd, where there is one digit before the de- 
cimal point and the number of digits after it is equal 
to the precision; when the precision is missing, 6 di- 
gits are produced; if the precision is zero, no decimal 
point appears. The E format code produces a number 
with E instead of e introducing the exponent The ex- 
ponent always contains at least two digits. 

g,G The float or double arg is printed in style f or e (or in 

style E in the case of a G format code), with the preci- 
sion specifying the number of significant digits. The 
style used depends on the value converted: style e is 
used only if the exponent resulting from the conver- 
sion is less than -4 or greater than the precision. 
Trailing zeroes are removed from the result; a de- 
cimal point appears only if it is followed by a digit 

c The character arg is printed. 
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s The org is taken to be a string (character pointer) and 

characters from the string are printed until a null char- 
acter (\ 0) is encountered or the number of characters 
indicated by the precision specification is reached. If 
the precision is missing, it is taken to be infinite, so all 
characters up to the first null character are printed. A 
NULL value for org yields undefined results. 

% Print a % ; no argument is converted. 

In no case does a non-existent or small field width cause trunca- 
tion of a field; if the result of a conversion is wider than the field 
width, the field is simply expanded to contain the conversion 
result Characters generated by print f and f print f are print- 
ed as if putc(3S) had been called. 

RETURN VALUE 

Each function returns the number of characters transmitted (not 
including the \0 in the case of sprint f), or a negative value if 
an output error was encountered. 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02", 
where wkday and mnth are pointers to null-terminated strings: 

printf("%s, %s %d, %.2d:%.2d", wkday, mnth, day, hr, min) ; 

To print pi to 5 decimal places: 

printf ("pi=% . 5f ", 4*atan (1.0)) ; 

SEE ALSO 

ecvt(3C), intro(3), putc(3S), scanf (3S). 



February, 1990 

Revision C 



putc(3S) putc(3S) 



NAME 

putc, putchar, fputc, putw — put character or word on a 
stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 

int c; 

FILE * stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 

int c; 

FILE * stream; 

int putw (w, stream) 
int w; 
FILE * stream; 

DESCRIPTION 

The putc macro writes the character c onto the output stream at 
the position where the file pointer, if defined, is pointing. The 
putchar macro is defined as putc (c, stdout) . 

fputc behaves like putc, but is a function rather than a macro. 
fputc runs more slowly than putc, but it takes less space per 
invocation and its name can be passed as an argument to a func- 
tion. 

putw writes the word (32-bit integer on the Macintosh II) w to the 
output stream at the position at which the file pointer, if defined, is 
pointing, putw neither assumes nor causes special alignment in 
the file. 

Output streams, with the exception of the standard error stream 
stderr, are by default buffered if the output refers to a file and 
line-buffered if the output refers to a terminal. The standard error 
output stream stderr is by default unbuffered, but use of 
f reopen (see f open(3S)) causes it to become buffered or line- 
buffered. When an output stream is unbuffered information, it is 
queued for writing on the destination file or terminal as soon as 
written; when it is buffered, many characters are saved up and 
written as a block; when it is line-buffered, each line of output is 
queued for writing on the destination terminal as soon as the line 
is completed (i.e., as soon as a newline character is written or ter- 
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minal input is requested), setbuf (3S) may be used to change 
the stream's buffering strategy. 

RETURN VALUE 

On success, these functions each return the value they have writ- 
ten. On failure, they return the constant EOF. This occurs if the 
file stream is not open for writing or if the output file cannot be 
grown. Because EOF is a valid integer, ferror(3S) should be 
used to detect putw errors. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), 
getc(3S), printf(3S), puts(3S), setbuf(3S). 

BUGS 

Because it is implemented as a macro, putc treats incorrectly a 
stream argument with side effects. In particular, putc(c, 
* f ++ ) ; doesn't work sensibly, f put c should be used instead. 
Because of possible differences in word length and byte ordering, 
files written using putw are machine-dependent and may not be 
read using getw on a different processor. 
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NAME 

putenv — change or add value to environment 

SYNOPSIS 

int putenv (string) 
char * string; 

DESCRIPTION 

string points to a string of the form "name-value", putenv 
makes the value of the environment variable name equal to value 
by altering an existing variable or creating a new one. In either 
case, the string pointed to by string becomes part of the environ- 
ment, so altering the string will change the environment The 
space used by string is no longer used once a new string-defining 
name is passed to putenv. 

RETURN VALUE 

putenv returns nonzero if it was unable to obtain enough space 
via mall oc for an expanded environment, otherwise zero. 

SEE ALSO 

exec(2), getenv(3C), malloc(3C), environ(5). 

WARNINGS 

putenv manipulates the environment pointed to by environ, 
and can be used in conjunction with getenv. However, envp 
(the third argument to main) is not changed. 
This routine uses malloc(3C) to enlarge the environment 
After putenv is called, environmental variables are not in alpha- 
betical order. 

A potential error is to call putenv with an automatic variable as 
the argument, then exit the calling function while string is still part 
of the environment. 
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NAME 

putpwent — write password file entry 

SYNOPSIS 

tinclude <pwd.h> 

int putpwent (p f f) 
struct passwd *p; 
FILE */; 

DESCRIPTION 

putpwent is the inverse of getpwent(3C). Given a pointer to 
a passwd structure created by getpwent (or getpwuid or 
getpwnam), putpwuid writes a line on the stream / which 
matches the format of /etc /passwd. 

The <pwd . h> header file is described in getpwent(3C). 

RETURN VALUE 

putpwent returns nonzero if an error was detected during its 
operation; otherwise it returns zero. 

SEE ALSO 

getpwent(3C). 

WARNINGS 

The above routine uses <stdio . h>. Therefore, the size of pro- 
grams not otherwise using standard I/O is increased more than 
might be expected. 
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NAME 

put s , f pu t s — put a string on a stream 

SYNOPSIS 

♦include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char *s; 
FILE * stream; 

DESCRIPTION 

puts writes the null-terminated string referenced by s, followed 
by a newline character, to the standard output stream stdout. 

fputs writes the null-terminated string pointed to by s to the 
named output stream. 

Neither function writes the terminating null character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), print f(3S), 
putc(3S). 

RETURN VALUE 

On success, both routines return the number of characters written. 

Both functions return EOF on error. This occurs if the routines try 
to write on a file that has not been opened for writing. 

NOTES 

puts appends a newline character while fputs does not 
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NAME 

qsort — quicker sort 

SYNOPSIS 

void qsort {base, nel, width, compar) 
char *base; 
unsigned nel, width; 
int (* compar) () ; 

DESCRIPTION 

qsort is an implementation of the quicker-sort algorithm. It 
sorts a table of data in place. 

base points to the element at the base of the table, nel is the 
number of elements in the table, width is the width of an element 
in bytes, compar is the name of the comparison function, which is 
called with two arguments that point to the elements being com- 
pared. The function must return an integer less than, equal to, or 
greater than zero according as the first argument is to be con- 
sidered less than, equal to, or greater than the second. 

NOTES 

The pointer to the base of the table should be of type pointer-to- 
element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbi- 
trary data may be contained in the elements in addition to the 
values being compared. The order in the output of the two items 
which compare as equal is unpredictable. 

EXAMPLES 

struct entry { 



}; 

main () 
{ 



char *name; 
int flags; 



struct entry hp[100]; 
int entcmpO; 

int i, count; 

for (i = 0; i < (count = 100); i++) { 

/* fill the structure with the name 
and flags */ 

} 

qsort ( (char *) hp, count, sizeof (hp[0]), entcmp) 
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entcmp (ep,ep2) 

struct entry *ep, *ep2; 

{ 

return (strcmp (ep->name, ep2->name) ) ; 
} 

will sort a set of names with associated flags in ASCII order. 

SEE ALSO 

sort(l), bsearch(3C), lsearch(3C), string(3C). 
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NAME 

rand, s rand — simple random-number generator 

SYNOPSIS 

int rand ( ) 

void srand(seed) 
unsigned seed; 

DESCRIPTION 

rand uses a multiplicative congruential random-number genera- 
tor with period 2 power of 32 that returns successive pseudo- 
random numbers in the range from to 32767. 

srand can be called at any time to reset the random-number gen- 
erator to a random starting point The generator is initially seeded 
with a value of 1. 

NOTES 

The spectral properties of rand leave a great deal to be desired. 
drand4 8(3C) provides a much better, though more elaborate, 
random-number generator. 

SEE ALSO 

drand4 8(3C). 



February, 1990 

Revision C 



rand(3F) rand(3F) 



NAME 

irand, srand, rand — Fortran uniform random-number 
generator 

SYNOPSIS 

call srand (iseed) 

/=irand() 
x=rand ( ) 

DESCRIPTION 

irand generates successive pseudo-random numbers in the range 
from to 2**15-1. rand generates pseudo-random numbers dis- 
tributed in (0, 1.0). srand uses its integer argument to reinitial- 
ize the seed for successive invocations of irand and rand. 

SEE ALSO 

rand(3C). 
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NAME 

rcmd, rresvport, ruserok — routines for returning a 
stream to a remote command 

SYNOPSIS 

int rcmd(ahost, inport, locuser, remuser, cmd,fd2p) 

char **ahost; 

u_short inport; 

char *locuser, *remuser, *cmd; 

int *fd2p; 

int rresvport (port) 
int *port; 

int ruserok (rhost, superuser, user, user) 

char *rhost; 

int superuser; 

char *ruser, *luser; 

DESCRIPTION 

rcmd is a routine used by the superuser to execute a command on 
a remote machine using an authentication scheme based on 
reserved port numbers, rresvport is a routine which returns a 
descriptor to a socket with an address in the privileged port space, 
ruserok is a routine used by servers to authenticate clients re- 
questing service with rcmd. All three functions are present in the 
same file and are used by the remshd(lM) server, as well as oth- 
ers. 

rcmd looks up the host *ahost, returning -1 if the host does not 
exist Otherwise *ahost is set to the standard name of the host and 
a connection is established to a server residing at the well-known 
Internet port inport. 

If the call succeeds, a socket of type S0CK_STREAM is returned 
to the caller, and given to the remote command as stdin and 
stdout. Iifd2p is nonzero, then an auxiliary channel to a con- 
trol process will be set up, and a descriptor for it will be placed in 
*fd2p. The control process will return the stderr (descriptor 2 
of the remote(lM) command) on this channel and will accept 
bytes on this channel as A/UX signal numbers to be forwarded to 
the process group of the command. If fdlp is 0, then the stderr 
(descriptor 2 of the remote(lM) command) will be made the 
same as stdout; no provision will be made for sending arbitrary 
signals to the remote process, although you may be able to get its 
attention by using out-of-band data. 
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The protocol is described in detail in remshd(lM). 

The rresvport routine is used to obtain a socket with a 
privileged address bound to it. This socket is suitable for use by 
rcmd and several other routines. Privileged addresses consist of a 
port in the range to 1023. Only the superuser is allowed to bind 
an address of this sort to a socket 

ruserok takes a remote host's name, two user names, and a flag 
indicating if the local user's name is the superuser. It then checks 
the files /etc/hosts. equiv and, possibly, .rhosts in the 
current working directory (normally the local user's home directo- 
ry) to see if the request for service is allowed. A is returned if 
the machine name is listed in the hosts . equiv file or the host 
and remote user name are found in the . rhosts file; otherwise 
ruserok returns -1. If the superuser flag is 1, the checking of 
the host . equiv file is bypassed. 

SEE ALSO 

remsh(lN), rlogin(lN), remshd(lM), rexecd(lM), 
rlogind(lM), rexec(3N). 

BUGS 

There is no way to specify options to the socket call which 
rcmd makes. 
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NAME 

regcmp, regex — compile and execute a regular expression 

SYNOPSIS 

char * regcmp (string! [, string! , . ..], (char *)0)) 
char *stringl, *string2 r ...; 

char *regex(re, subject [, retO, ...]) 
char *re, ^subject, *retO, ...; 

extern char *locl; 

DESCRIPTION 

regcmp compiles a regular expression and returns a pointer to 
the compiled form. malloc(3C) is used to create space for the 
vector. It is the user's responsibility to free unneeded space that 
has been allocated by malloc. A NULL return from regcmp 
indicates an incorrect argument, regcmp(l) has been written to 
generally preclude the need for this routine at execution time. 

regex executes a compiled pattern against the subject string. 
Additional arguments are passed to receive values back, regex 
returns NULL on failure or a pointer to the next unmatched char- 
acter on success. A global character pointer loci points to 
where the match began, regcmp and regex were mostly bor- 
rowed from the editor, ed(l); however, the syntax and semantics 
have been changed slightly. The following are the valid symbols 
and their associated meanings. 

[ ] * . " These symbols retain their current meaning. 

$ This symbol matches the end of the string; \n 

matches the newline. 

Within brackets the minus means "through." For 
example, [a-z] is equivalent to [abed. . .xyz]. 
The - can appear as itself only if used as the last or 
first character. For example, the character class ex- 
pression []-] matches the characters ] and-. 

+ A regular expression followed by + means "one or 

more times." For example, [ 0-9 ] + is equivalent to 
[0-9] [0-9]*. 

{m} {m,} {m,u) Integer values enclosed in { } indicate the 
number of times the preceding regular expression is 
to be applied. The minimum number is m and the 
maximum number is u, which must be less than 256. 
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If only m is present (e.g., { m } ), it indicates the ex- 
act number of times the regular expression is to be 
applied, {m, } is analogous to {m.infinity}. 
The plus (+) and star (*) operations are equivalent to 
{I,} and { , } , respectively. 

( ... ) $n 

The value of the enclosed regular expression is to be 
returned. The value will be stored in the (n+l)\h ar- 
gument following the subject argument. At present, 
at most 10 enclosed regular expressions are allowed, 
regex makes its assignments unconditionally. 

(...) Parentheses are used for grouping. An operator (e.g., 
*, +, { } ) can work on a single character or a regu- 
lar expression enclosed in parentheses. For example, 
(a*(cb+)*)$0. 

By necessity, all the above defined symbols are special. They 
must, therefore, be escaped to be used as themselves. 

EXAMPLES 
Example 1: 

char * cursor, * newcursor, *ptr; 

newcursor = regex ( (ptr = regcmp ("~\n", 0)), cursor); 
free (ptr) ; 

This example will match a leading newline in the subject string 
pointed at by cursor. 

Example 2: 

char ret0[9] ; 

char *newcursor, *name; 

name = regcmp ("( [A-Za-z] [A-za-z0-9_] {0, 7} ) $0", 0) ; 
newcursor = regex (name, "123Testing321", retO); 

This example will match through the string *'Testing3" and 
will return the address of the character after the last matched char- 
acter (cursor+11). The string "Testing3" will be copied to the 
character array retO. 
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Example 3: 

♦include "file.i" 
char * string, *newcursor; 

newcursor - regex (name, string) ; 

This example applies a precompiled regular expression in 
file . i (see regcmp(l)) against string. 

This routine is kept in /lib/libPW . a. 

SEE ALSO 

ed(l), regcmp(l), malloc(3C). 

BUGS 

The user program may run out of memory if regcmp is called 
iteratively without freeing the vectors no longer required. The fol- 
lowing user-supplied replacement for malloc(3C) reuses the 
same vector, saving time and space: 

/* user's program */ 

char * 
malloc (n) 
unsigned n; 
{ 

static char rebuf [512]; 

return (n <= sizeof rebuf) ? rebuf : NULL; 
} 
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NAME 

res_mkquery, res_send, res_init, dn_comp, 
dn_expand — resolver routines 

SYNOPSIS 

#include <sys /types . h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 

res_mkquery {op, dname, class, type, data, datalen, 

newrr, buf, buflen) 
int op; 
char * dname; 
int class, type; 
char *data; 
int datalen; 
struct rrec *newrr; 
char *buf; 
int buflen; 

res_send (msg, msglen, answer, anslen) 
char *msg; 
int msglen; 
char * answer; 
int anslen; 

res_init () 

dn_comp (exp_dn, comp_dn, length, dnptrs, lastdnptr) 

char *exp_dn, *comp_dn; 

int length; 

char ** dnptrs, ** lastdnptr; 

dn_expand(m.sg, eomorig, compjin, exp_dn, length) 
char *msg, *eomorig, *comp_dn, expdn; 
int length; 

DESCRIPTION 

These routines are used for making, sending, and interpreting 
packets to Internet domain name servers. Global information that 
is used by the resolver routines is kept in the variable _res. 
Most of the values have reasonable defaults and can be ignored. 
Options stored in _res . options are defined in resolv . h and 
are as follows. Options are a simple bit mask. 
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RES_INIT 

True if the initial name server address and default domain 
name are initialized (for example, res_init has been 
called). 

RES_DEBUG 

Print debugging messages. 

RES_AAONLY 

Accept authoritative answers only. res_send will continue 
until it finds an authoritative answer or finds an error. 
Currently this is not implemented. 

RES_USEVC 

Use TCP connections for queries instead of UDP. 

RES_STAYOPEN 

Used with RES_USEVC to keep the TCP connection open 
between queries. This is useful only in programs that regu- 
larly do many queries. UDP should be the normal mode 
used. 

RES_IGNTC 

Unused currently (ignore truncation errors — don't retry with 
TCP). 

RES_RECURSE 

Set the recursion desired bit in queries. This is the default. 
(res_send does not do iterative queries and expects the 
name server to handle recursion.) 

RES_DEFNAMES 

Append the default domain name to single label queries. This 
is the default. 

res_init 

reads the initialization file to get the default domain name and the 
Internet address of the initial hosts running the name server. If 
this line does not exist, the host running the resolver is tried. 
res_mkquery makes a standard query message and places it in 
buf. res_mkquery will return the size of the query or -1 if the 
query is larger than buflen. op is usually QUERY but can be any 
of the query types defined in nameser . h. dname is the domain 
name. If dname consists of a single label and the 
res_defnames flag is enabled (the default), dname will be ap- 
pended with the current domain name. The current domain name 
is defined in a system file and can be overridden by the environ- 
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ment variable LOCALDOMAIN. newrr is currently unused but is 
intended for making update messages. 

res_send sends a query to name servers and returns an answer. 
It will call res_init if RES_INIT is not set, send the query to 
the local name server, and handle timeouts and retries. The length 
of the message is returned or -1 if there were errors. 

dn_expand expands the compressed domain name comp_dn to 
a full domain name. Expanded names are converted to uppercase. 
msg is a pointer to the beginning of the message, expdn is a 
pointer to a buffer of size length for the result. The size of 
compressed name is returned or -1 if there was an error. 

dn_comp compresses the domain name exp_dn and stores it in 
comp_dn. The size of the compressed name is returned or -1 if 
there were errors, length is the size of the array pointed to by 
comp_dn. dnptrs is a list of pointers to previously compressed 
names in the current message. The first pointer points to to the be- 
ginning of the message and the list ends with NULL, lastdnptr is 
a pointer to the end of the array pointed to dnptrs. A side effect is 
to update the list of pointers for labels inserted into the message 
by dncomp as the name is compressed. If dnptr is NULL, we 
don't try to compress names. If lastdnptr is NULL, we don't up- 
date the list. 

FILES 

/etc/resolv.conf 

SEE ALSO 

named(lM), resolver(4). 
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NAME 

rexec — return stream to a remote command 

SYNOPSIS 

int rexec (ahost, inport, user, passwd, cmd, fd2p) ; 

char ** ahost; 

u_short inport; 

char *user, *passwd, *cmd; 

int *fd2p; 

DESCRIPTION 

rexec looks up the host referenced by *ahost using 
gethostbyname(3N), returning -1 if the host does not exist. 
Otherwise * ahost is set to the standard name of the host If a 
username and password are both specified, then these are used to 
authenticate to the foreign host; otherwise the environment and 
then the user's . net re file in his home directory are searched for 
appropriate information. If all this fails, the user is prompted for 
the information. 

The port inport specifies which well-known DARPA Internet port 
to use for the connection; it will normally be the value returned 
from the call 

get servbyname ("exec", "tcp") 

(see getservent(3N)). The protocol for connection is 
described in detail in rexecd(lM). 

If the call succeeds, a socket of type SOCK_STREAM is returned 
to the caller, and given to the remote command as stdin and 
stdout. If fd2p is nonzero, then a auxiliary channel to a control 
process will be setup and a descriptor for it will be placed in 
*fd2p. The control process will return diagnostic output from the 
command (unit 2) on this channel, and will also accept bytes on 
this channel as being A/UX signal numbers, to be forwarded to the 
process group of the command. Iffd2p is 0, then the stderr 
(unit 2 of the remote command) will be made the same as the 
stdout and no provision is made for sending arbitrary signals to 
the remote process, although you may be able to get its attention 
by using out-of-band data. 

SEE ALSO 

rcmd(3N), rexecd(lM). 



February, 1990 
Revision C 



rexec(3N) rexec(3N) 



BUGS 

There is no way to specify options to the socket call which 
rexec makes. 
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NAME 

musers, rusers — return information about users on remote 
machines 

SYNOPSIS 

♦include <rpcsvc/rusers.h> 

rnusers (host) 
char *host; 

rusers (host, up) 

char *host; 

struct utmpidlearr *up; 

DESCRIPTION 

rnusers returns the number of users logged on to host (or -1 if 
it cannot determine that number), rusers fills the structure 
utmpidlearr with data about host, and returns if successful. 
The relevant structures are 

struct utmparr { /* RUSERSVERS_ORIG */ 

struct utmp **uta_arr; 

int uta_cnt 
In- 
struct utmpidle { 

struct utmp ui_utmp; 

unsigned ui_idle; 
}; 

struct utmpidlearr { /* RUSERSVERS_IDLE */ 
struct utmpidle **uia_arr; 
int uia_cnt 

}; 

RPCINFO 

Program number: RUSERSPROG 

xdr routines: 

int xdr_utmp (xdrs, up) 

XDR *xdrs; 

struct utmp *up; 
int xdr_utmpidle (xdrs, ui) ; 

XDR *xdrs; 

struct utmpidle *ui; 
int xdr_utmpptr (xdrs, up); 

XDR *xdrs; 

struct utmp **up; 
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int xdr_utmpidleptr (xdrs, up) ; 

XDR *xdrs; 

struct utmpidle **up; 
int xdr_utmparr (xdrs, up) ; 

XDR *xdrs; 

struct utmparr *up; 
int xdr_utmpidlearr (xdrs, up) ; 

XDR *xdrs; 

struct utmpidlearr *up; 

Procs: 

RUSERSPROC_NUM 

No arguments; returns number of users as an unsigned 
long. 

RUSERSPROC_NAMES 

No arguments; returns utmparr or utmpidlearr, 
depending on version number. 

RUSERSPROC_ALLNAMES 

No arguments; returns utmparr or utmpidlearr, 
depending on version number. Returns listing even for utmp 
entries satisfying nonuser ( ) in utmp . h. 

Versions: 

RUSERSVERS_ORIG, RUSERSVERS_IDLE 

SEE ALSO 

rusers(l), rusersd(lM). 
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NAME 

anint, dnint, nint, idnint — Fortran nearest integer 
functions 

SYNOPSIS 

integer i 

real rl , r2 

double precision dpi, dp2 

r2=anint (rl) 
i=nint (rl) 

dp2=anint (dpi) 
dp2=dnint (dpi) 

z=nint (dpi) 
i=idnint (dpi) 

DESCRIPTION 

anint returns the nearest whole real number to its real argument 
(i.e., int(a+0.5) if a > 0, int(a-0.5) otherwise). 
dnint does the same for its double-precision argument nint 
returns the nearest integer to its real argument, idnint is the 
double-precision version, anint is the generic form of anint 
and dnint, performing the same operation and returning the data 
type of its argument, nint is also the generic form of idnint. 
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NAME 

rpc — library routines for remote procedure calls 

DESCRIPTION 

These routines allow C programs to make procedure calls on other 
machines across the network. First, the client calls a procedure to 
send a data packet to the server. Upon receipt of the packet, the 
server calls a dispatch routine to perform the requested service, 
and then sends back a reply. Finally, the procedure call returns to 
the client 



FUNCTIONS 

auth_destroy ( ) 

authnone_create ( ) 
authunix create () 



authunix_create_default () 
callrpc () 

clnt_broadcast () 

clnt_call () 

clnt_destroy ( ) 
clnt_freeres () 

clnt_geterr ( ) 

clnt_pcreateerror ( ) 



destroy authentication in- 
formation handle 

return RPC authentication 
handle with no checking 

return RPC authentication 
handle with A/UX permis- 
sions 



return default A/UX 
thentication handle 



au- 



call remote procedure, 

given 

[prognum,versniunj}rocnwn] 

broadcast remote procedure 
call everywhere 

call remote procedure asso- 
ciated with client handle 

destroy client's RPC handle 

free data allocated by 
RPC/XDR system when 
decoding results 

copy error information 
from client handle to error 
structure 

print message to stderr 
about why client handle 
creation failed 
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clnt_perrno () 

clnt_j?error () 
clnt_sperrno ( ) 

clnt_sperror ( ) 
clntraw_create () 

clnttcp_create () 

clntudp_create () 

get_myaddress () 

pmap_getmaps ( ) 

pmap_getport () 

pmap_rmtcall () 
pmap_set ( ) 

pmap_unset ( ) 

registerrpc () 
rpc_createerr 



pint message to stderr 
corresponing to condition 
given 

print message to stderr 
about why RPC call failed 

print message to a string 
corresponding to condition 
given 

print message to a string 

create toy RPC client for 
simulation 

create RPC client using 
TCP transport 

create RPC client using 
UDP transport 

get the machine's IP ad- 
dress 

return list of RPC 
program-to-port mappings 

return port number on 
which waits supporting ser- 
vice 

instructs portmapper to 
make an RPC call 

establish mapping between 
[prognum,versnum,procnum] 
and port 

destroy mapping between 
[prognum,versnumj)rocnum\ 
and port 

register procedure with 
RPC service package 

global variable indicating 
reason why client creation 
failed 
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svc_destroy () 

svc_fds 

svc_f reeargs ( ) 

svc_getargs () 
svc_getcaller ( ) 
svc_getreq() 
svc_register ( ) 

svc_run ( ) 

svc_sendreply ( ) 
svc_unregister ( ) 

svcerr_auth() 

svcerr_decode ( ) 
svcerr_noproc () 

svcerr_noprog ( ) 

svcerr_progvers ( ) 



destroy RPC service tran- 
sport handle 

global variable with RPC 
service file descriptor mask 

free data allocated by 
RPC/XDR system when 
decoding arguments 

decodes the arguments of 
an RPC request 

get the network address of 
the caller of a procedure 

returns when all associated 
sockets have been serviced 

associates prognum and 
versnum with service 
dispatch procedure 

wait for RPC requests to 
arrive and call appropriate 
service 

send back results of a re- 
mote procedure call 

remove mapping of 
[prognum.versnum] to 

dispatch routines 

called when refusing ser- 
vice because of authentica- 
tion error 

called when service cannot 
decode its parameters 

called when service hasn't 
implemented the desired 
procedure 

called when program is not 
registered with RPC pack- 
age 

called when version is not 
registered with RPC pack- 
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svcerr_systemerr () 
svcerr_weakauth () 

svcraw_create ( ) 
svctcp_create ( ) 
svcudp_create ( ) 
xdr_accepted_reply ( ) 
xdr_authunix_parms () 
xdr_callhdr () 

xdr_callmsg ( ) 

xdr_opaque_auth ( ) 
xdrjpmap ( ) 

xdr_pmaplist ( ) 
xdr_re jected_reply ( ) 

xdr_replymsg ( ) 
xprt register () 



age 

called when service detects 
system error 

called when refusing ser- 
vice because of insufficient 
authentication 

creates a toy RPC service 
transport for testing 

creates an RPC service 
based on TCP transport 

creates an RPC service 
based on UDP transport 

generates RPC-style replies 
without using RPC package 

generates A/UX credentials 
without using RPC package 

generates RPC-style 

headers without using RPC 
package 

generates RPC-style mes- 
sages without using RPC 
package 

describes RPC messages, 
externally 

describes parameters for 
portmap procedures, exter- 
nally 

describes a list of port map- 
pings, externally 

generates RPC-style rejec- 
tions without using RPC 
package 

generates RPC-style replies 
without using RPC package 

registers RPC service tran- 
sport with RPC package 
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xprt_un register () unregisters RPC service 

transport from RPC pack- 
age 

SEE ALSO 

AIUX Network Applications Programming. 
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NAME 

rtmp_netinfo — identify AppleTalk node and bridge 
addresses 

SYNOPSIS 

#include <at/appletalk.h> 
cc \flags] files -lat [libraries] 

int rtmp_netinf o {fd, addr, bridge) 

int fd; 

at_inet_t *addr, * bridge; 

DESCRIPTION 

This routine allows the caller to determine node addresses. It 
uses the structure at_inet_t defined in 
<at /appletalk . h>: 



typedef struct at 


inet 


{ 


at net 




net; 


at node 




node; 


at_socket 




socket; 


} at_inet_t ; 







The at_inet_t structure specifies AppleTalk socket internet 
address. The parameters are 

fd An AppleTalk socket descriptor. If this parameter is 

-1, it is ignored; otherwise, upon return, the socket 
field in addr contains the socket number correspond- 
ing to fd. 

addr Pointer to an at_inet_t structure. If this pointer is 

non-NULL, the AppleTalk network and node ad- 
dresses are returned in the structure to which it points. 
If fd is not -1, the socket field of this structure is 
filled, otherwise it is zero. This parameter is ignored 
if it is NULL. 

bridge Pointer to an at_inet_t structure. If this pointer is 
non-NULL, the AppleTalk network and addresses of 
a bridge known to DDP are returned in the structure 
to which it points. This parameter is ignored if it is 
NULL. The socket field is meaningless and always 
contains zero on return. 
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Either addr or bridge must be non-NULL. rtmp_netinf o re- 
turns an error if both are NULL. 

The function returns zero if successful; otherwise, -1 is returned 
with a detailed error code inerrno. 

DIAGNOSTICS 

rtmp_netinf o returns -1 on error with a detailed error code in 

errno: 

[einval] Both addr and bridge are NULL 

See also the errors returned by the underlying DDP module. 

SEE ALSO 

ddp(3N), Inside AppleTalk; "AppleTalk Programming Guide," 
in AIUX Network Applications Programming. 
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NAME 

rwall — write to specified remote machines 

SYNOPSIS 

tinclude <rpcsvc/ rwall. h> 

rwall (host, msg) ; 
char *host, *msg; 

DESCRIPTION 

rwall causes host to print the string msg to all its users. It re- 
turns if successful. 

RPC INFO 

Program number: wallprog 

Procs: 

WALLPROC_WALL 

Takes string as argument (wrapstring); returns no arguments. 
Executes wall on remote host with string. 

Versions: rstatvers_orig 

SEE ALSO 

rwall(lM), shutdown(8), rwalld(lM). 
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NAME 

scandir — scan a directory 

SYNOPSIS 

finclude <sys/types.h> 
♦include <sys/dir.h> 

scandir (dirname, namelist, select, compar) 

char * dirname ; 

struct direct * (* namelist [] ) ; 

int (* select) () ; 

int (* compar) () ; 

alphasort (dl , d2) 

struct direct **dl, **d2; 

DESCRIPTION 

scandir reads the directory dirname and builds an array of 
pointers to directory entries using malloc(3). It returns the 
number of entries in the array and a pointer to the array through 
namelist. 

The select parameter is a pointer to a user supplied subroutine 
which is called by scandir to select which entries are to be in- 
cluded in the array. The select routine is passed a pointer to a 
directory entry and should return a non-zero value if the directory 
entry is to be included in the array. If select is null, then all the 
directory entries will be included. 

The compar parameter is a pointer to a user supplied subroutine 
which is passed to qsort(3) to sort the completed array. If this 
pointer is null, the array is not sorted, alphasort is a routine 
which can be used for the compar parameter to sort the array al- 
phabetically. 

The memory allocated for the array can be deallocated with free 
(see malloc(3)) by freeing each pointer in the array and the ar- 
ray itself. 

RETURN VALUE 

Returns -1 if the directory cannot be opened for reading or if can- 
not allocate enough memory to hold all the data structures. 

SEE ALSO 

directory(3), malloc(3C), malloc(3X), qsort(3C), 
dir(4). 
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NAME 

scanf, fscanf, sscanf — convert formatted input 

SYNOPSIS 

#include <stdio.h> 

int scanf {format [, pointer]. . . ) 
char * format; 

int fscanf (stream, format [, pointer]. . . ) 
FILE * stream; 
char * format; 

int sscanf (s, format [, pointer]. . . ) 
char *s, * format; 

DESCRIPTION 

scanf reads from the standard input stream stdin. fscanf 
reads from the named input stream, sscanf reads from the char- 
acter string at *s. Each function reads characters, interprets them 
according to format, and stores the results in the location specified 
by the pointer arguments. Each function expects as arguments: a 
control string format (described below) and a set of pointer argu- 
ments indicating where the converted input should be stored. 

The control string usually contains conversion specifications, 
which are used to direct interpretation of input sequences. The 
control string may contain: 

1. White-space characters (blanks and tabs) which, except in two 
cases described below, cause input to be read up to the next 
nonwhite-space character. 

2. An ordinary character (not %), which must match the next 
character of the input stream. 

3. Conversion specifications, consisting of the character %, an op- 
tional assignment suppression character *, an optional numeri- 
cal maximum field width, an optional letter 1 or h indicating 
the size of the receiving variable, and a conversion code. 

A conversion specification directs the conversion of the next input 
field; the result is placed in the variable pointed to by the 
corresponding argument, unless assignment suppression has been 
indicated by *. The suppression of assignment provides a way of 
describing an input field which is to be skipped. An input field is 
defined as a string of nonwhite-space characters; it extends to the 
next inappropriate character or until the field width, if specified, is 
exhausted. For all descriptors except " [" and "c", white space 
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leading an input field is ignored. 

The conversion code indicates the interpretation of the input field; 
the corresponding pointer argument must usually be of a restricted 
type. For a suppressed field, no pointer argument should be given. 
The following conversion codes are legal: 

% A single % is expected in the input at this point; no assign- 
ment is done. 

d A decimal integer is expected; the corresponding argument 
should be an integer pointer. 

u An unsigned decimal integer is expected; the correspond- 
ing argument should be an unsigned integer pointer. 

o An octal integer is expected; the corresponding argument 
should be an integer pointer. 

x A hexadecimal integer is expected; the corresponding argu- 
ment should be an integer pointer. 

e,f ,g A floating point number is expected; the next field is con- 
verted accordingly and stored through the corresponding 
argument, which should be a pointer to a float . The input 
format for floating point numbers is an optionally signed 
string of digits, possibly containing a decimal point, fol- 
lowed by an optional exponent field consisting of an E or 
an e, followed by an optional +, -, or space followed by an 
integer. 

s A character string is expected; the corresponding argument 
should be a character pointer to an array of characters large 
enough to accept the string and a terminating \0, which 
will be added automatically. The input field is terminated 
by a white-space character. 

c A character is expected; the corresponding argument 
should be a character pointer. The normal skip over white 
space is suppressed in this case; to read the next nonspace 
character, use % Is. If a field width is given, the 
corresponding argument should refer to a character array; 
the indicated number of characters is read. 

[ String data and the normal skip over leading white space is 
suppressed. The left bracket is followed by a set of charac- 
ters (the scanset) and a right bracket; the input field is the 
maximal sequence of input characters consisting entirely of 



February, 1990 

Revision C 



scanf(3S) scanf(3S) 



characters in the scanset. The caret, (~), when it appears as 
the first character in the scanset, serves as a complement 
operator and redefines the scanset as the set of all charac- 
ters not contained in the remainder of the scanset string. 
There are some conventions used in the construction of the 
scanset. A range of characters may be represented by the 
construct first-last; thus, [0123456789] may be ex- 
pressed [ - 9 ] . Using this convention, first must be lexi- 
cally less than or equal to last, or else the dash will stand 
for itself. The dash will also stand for itself whenever it is 
the first or the last character in the scanset. To include the 
right square bracket as an element of the scanset, it must 
appear as the first character (possibly preceded by a 
circumflex) of the scanset', otherwise it will be interpreted 
syntactically as the closing bracket. The corresponding ar- 
gument must point to a character array large enough to hold 
the data field and the terminating \0, which will be added 
automatically. At least one character must match for this 
conversion to be considered successful. 

The conversion characters d, u, o, and x may be preceded by 1 or 
h to indicate that a pointer to long or short, rather than int, is 
in the argument list. Similarly, the conversion characters e, f , 
and g may be preceded by 1 to indicate that a pointer to double, 
rather than float, is in the argument list. 

The 1 or h modifier is ignored for other conversion characters, 
scanf conversion terminates at EOF, at the end of the control 
string, or when an input character conflicts with the control string. 
In the latter case, the offending character is left unread in the input 
stream. 

scanf returns the number of successfully matched and assigned 
input items; this number can be zero when an early conflict 
between an input character and the control string occurs. If the in- 
put ends before the first conflict or conversion, EOF is returned. 

EXAMPLES 
The call: 

int i; n; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 

with the input line 

25 54.32E-1 thompson 
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will assign the value 3 to n, the value 25 to i, and the value 
5 . 432 to x; name will contain thompson\0. 

The call 

int i; float x; char name[50]; 
(void) scanf ("%2d%f%*d %[0-9] M r &i, &x, 
name) ; 

with input 

56789 0123 56a72 

will assign 56 to /, 789 . to x, skip 0123, and place the string 
56\0 in name. The next call to get char (see getc(3S)) will 
return a. 

RETURN VALUE 

These functions return EOF on end of input and a short count for 
missing or illegal data items. 

NOTES 

Trailing white space is left unread unless matched in the control 
string. 

BUGS 

The success of literal matches and suppressed assignments is not 
directly determinable. 

SEE ALSO 

getc(3S),printf(3S), strtod(3C), strtol(3C). 
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NAME 

set 4 2 sig — set 4.2 BSD signal interface 

SYNOPSIS 

int set42sig() 

DESCRIPTION 

set 4 2 sig changes the signal interface to one closely resembling 
BSD 4.2 systems. This call is similar to the setcompat system 
call. Unlike setcompat(2), set 42 sig arranges for the current 
compatibility flags to be logically OR'ed with the new flags, 
set 4 2 sig is functionally equivalent to the following C code 
fragment: 

♦include <compat.h> 

return (setcompat (getcompat () | COMPAT_BSDSIGNALS | 
COMPAT_BSDTTY | COMPAT_BSDSYSCALLS) ) ; 

For the process calling it, it enables reliable signal delivery, the 
job control tty signals, and restarting of system calls when an in- 
terrupt is received. 

If the COMPAT_SViD flag is set before calling set42sig, both 
BSD 4.2 and System V modes are set and 4.2 BSD mode will 
have precedence. compat_svid can be set in two ways, by cal- 
ling setcompat (2) and by compiling the program with the -ZS 
flag option (see cc(l). 

All aspects of 4.2 signals are inherited across fork system calls. 
4.2 job control group membership is inherited across exec sys- 
tem calls. When exec is invoked, the inherited 4.2 signals are 
lost and the signal-handling mechanism returns to System V style. 
See setcompat(2) for more information. 

ERRORS 

[EINVAL] The process has already arranged to catch 

signals. Normally set 4 2 sig is called pri- 
or to any other signal activity. 

SEE ALSO 

cc(l), setcompat(2), sigvec(2), signal(3), ter- 
mio(7). 
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NAME 

setbuf , setvbuf — assign buffering to a stream 

SYNOPSIS 

♦include <stdio.h> 

void setbuf (stream, buf) 
FILE * stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 
FILE * stream; 
char *buf; 
int type, size; 

DESCRIPTION 

setbuf may be used after a stream has been opened but before it 
is read or written. It causes the array pointed to by buf to be used 
instead of an automatically allocated buffer. If buf is the NULL 
pointer input/output will be completely unbuffered. 

A constant bufsi z , defined in the <stdio . h> header file, tells 
how big an array is needed: 

char buf [BUFSIZ] ; 

setvbuf may be used after a stream has been opened but before 
it is read or written, type determines how stream will be buffered. 
Legal values for type (defined in stdio . h) are: 

_l OFBF causes input/output to be fully buffered. 

_iolbf causes output to be line buffered; the buffer will be 

flushed when a newline is written, the buffer is full, 
or input is requested. 

_ionbf causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used 
for buffering, instead of an automatically allocated buffer, size 
specifies the size of the buffer to be used. The constant bufsiz 
in <stdio . h> is suggested as a good buffer size. If input/output 
is unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other 
input/output is fully buffered. 
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RETURN VALUE 

If an illegal value for type or size is provided, setvbuf returns a 
nonzero value. Otherwise, the value returned will be zero. 

SEE ALSO 

f open(3S), getc(3S), intro(3), malloc(3C), putc(3S). 

NOTES 

A common source of error is allocating buffer space as an "au- 
tomatic" variable in a code block, and then failing to close the 
stream in the same block. 

setbuf allows assignment of a new I/O buffer after the stream 
has been read (written), and if unflushed data remains in the origi- 
nal buffer. This could lead to a loss of data error. 
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NAME 

set jmp, long jmp — non-local goto 

SYNOPSIS 

♦include <setjmp.h> 

int set jmp (env) 
jmp_buf env; 

void long jmp (env, val) 
jmp_buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts 
encountered in a low-level subroutine of a program. 

set jmp saves its stack environment in env for later use by 
longjmp. The environment type jmp_buf is defined in the 
<set jmp . h> header file. 

RETURN VALUE 

When set jmp has been called by the calling process, returns 0. 

longjmp restores the environment saved by the last call of 
set jmp with the corresponding env argument. After longjmp 
is completed, program execution continues as if the corresponding 
call of set jmp (which must not itself have returned in the inter- 
im) had just returned the value val. longjmp cannot cause 
set jmp to return the value 0. If longjmp is invoked with a 
second argument of 0, set jmp will return 1. All accessible data 
have values as of the time longjmp was called. 

SEE ALSO 

signal(3). 

WARNINGS 

longjmp fails if it is called when env was never primed by a call 
to set jmp or when the last such call is in a function which has 
since returned. 
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NAME 

setposix — set POSIX compatibility flags 

SYNOPSIS 

int setposix () 

DESCRIPTION 

setposix is equivalent to the following code fragment: 

♦include <compat.h> 
setcompat (COMPAT_POSIX) ; 

COMPAT_POSix is equivalent to all of the following: 

COMPAT_BSDGROUP S 

COMPAT_BSDCHOWN 

COMPAT_BSDS IGNALS 

COMPAT_BSDTTY 

COMPAT_SYSCALLS 

COMPAT_POS IXPATHTRUNC 

COMPAT_EXEC 

Any non-POSIX compatibility flags that were set prior to the call 
to setposix are reset 

RETURN VALUE 

Upon successful completion, setposix returns the previous 
compatibility mask. Otherwise, a value of -1 is returned and 
errno is set to indicate the error. 

ERRORS 

setposix will return the following error code: 

[einval] setposix results in a change in the state of 

the COMPAT_bsdsignals bit and a signal is 
currently pending, caught, or held. 

SEE ALSO 

setcompat (2). 
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NAME 

setuid, setgid — set user and group IDs 

SYNOPSIS 

int setuid (lUd) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

setuid (setgid) is used to set the real user (group) ID and ef- 
fective user (group) ID of the calling process. 

If the effective user ID of the calling process is superaser, the real 
user (group) ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not superuser, but 
its real user (group) ID is equal to uid (gid), the effective user 
(group) ID is set to uid (gid). 

If the effective user ID of the calling process is not superuser, but 
the saved set-user (group) ID from exec(2) is equal to uid (gid), 
the effective user (group) ID is set to uid(gid). 

RETURN VALUE 

Upon successful completion, a value of is returned. Otherwise, 
a value of -1 is returned and errno is set to indicate the error. 

ERRORS 

setuid (setgid) will fail if one of the following is true: 

[eperm] the real user (group) ID of the calling process is 

not equal to uid (gid) and its effective user ID is 
not superuser. 

[ E I nval ] The uid (gid) is out of range. 

SEE ALSO 

getuid(2), intro(2), setregid(2), setreuid(2). 
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NAME 

sigaction — examine or change signal action 

SYNOPSIS 

♦include <signal.h> 

int sigaction {sig, act, oact) 

int sig; 

struct sigaction *act, *oact; 

DESCRIPTION 

The system defines a set of signals that may be delivered to a pro- 
cess. Signal delivery resembles the occurrence of a hardware in- 
terrupt: the signal is blocked from further occurrence, the current 
process context is saved, and a new one is built. A process may 
specify a handler to which a signal is delivered, or specify that a 
signal is to be blocked or ignored. A process may also specify 
that a default action is to be taken by the system when a signal oc- 
curs. Normally, signal handlers execute on the current stack of 
the process. This may be changed, on a per-handler basis, so that 
signals are taken on a special "signal stack." 

All signals have the same priority. Signal routines execute with 
the signal that caused their invocation but other signals may yet 
occur. A global "signal mask" defines the set of signals currently 
blocked from delivery to a process. The signal mask for a process 
is initialized from that of its parent (normally 0). It may be 
changed with a sigprocmask(3P) call, or when a signal is 
delivered to the process. 

When a signal condition arises for a process, the signal is added to 
a set of signals pending for the process. If the signal is not 
currently blocked by the process then it is delivered to the process. 
When a signal is delivered, the current state of the process is 
saved, a new signal mask is calculated (as described below), and 
the signal handler is invoked. The call to the handler is arranged 
so that if the signal handling routine returns normally, the process 
resumes execution in the context from before the signal's delivery. 
If the process wishes to resume in a different context, then it must 
arrange to restore the previous context itself (see 
sigset jmp(3P). 

sigaction allows the calling process to examine or specify the 
action to be taken on delivery of a signal, sig specifies the signal 
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number. 

The sigaction structure is defined in <signal . h>: 

struct sigaction { 

void (*sa_handler) () ; 

sigset_t sa_mask; 

int sa_flags; 
}; 

If act is not NULL, it points to a structure specifying the action to 
be taken when the signal is delivered. If oact is not NULL, the ac- 
tion previously associated with the signal is stored in the location 
pointed to by oact. If act is NULL, signal handling is unchanged. 
When act is NULL, sigaction can be used to inquire about the 
current handling of a given signal. 

The sa_f lags field of act can be used to modify the delivery of 
a specific signal. If sig is SIGCHLD and the SA_NOCLDSTOP 
flag is not set in sa_f lags, a SIGCHLD signal is generated for 
the calling process if any of its child processes stop. If sig is 
SIGCHLD and the SA_NOCLDSTOP flag is set in sa_f lags, a 
SIGCHLD signal is not generated for stopped child processes. If 
the SA_ONSTACK bit is set in sa_f lags, the system delivers 
the signal to the process on a signal stack specified by sig- 
stack(2). If the SA_INTERRUPT bit is set in sa_f lags, sys- 
tem calls interrupted by a signal are not restarted. 

When a signal is caught by a signal-catching function, a new sig- 
nal mask is calculated and installed for the duration of the signal- 
catching function or until sigprocmaskO or sigsuspendO is 
called. This mask is formed by taking the union of the current sig- 
nal mask and the set associated with the action for the signal being 
delivered, such as sa_mask, and then including the signal being 
delivered. If and when the user's signal handler returns normally, 
the original signal mask is restored. 

Once an action is installed for a specific signal, it remains installed 
until another action is explicitly requested by another call to 
sigaction or until one of the exec functions is called. 

SIGKILL and SIGSTOP cannot be caught or ignored. The set of 
signals specified by sa_mask is not allowed to block these sig- 
nals. This is silently enforced. 
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If sigaction fails, no new signal handler is installed. 

A/UX POSIX defines the following signals: 

SIGHUP 1 hangup 

SIGINT 2 interrapt 

SIGQUIT 3* quit 

SI GILL 4* illegal instruction 

SIGABRT 6* aborted 

SIGFPE 8* floating-point exception 

S I GK I LL 9 kill (cannot be caught, blocked, or ignored) 

SIGSEGV 11* segmentation violation 

SIGPIPE 13 write on a pipe with no one to read it 

SIGALRM 14 alarm clock 

SIGTERM IS software termination signal 

SIGUSR1 16 user defined signal 1 

SIGUSR2 17 user defined signal 2 

SIGCLD 18* child status has changed 

SIGTSTP 20f stop signal generated from keyboard 

SIGTTIN 21f background read attempted from control terminal 

SIGTTOU 22f background write attempted to control terminal 

SIGSTOP 23 f stop (cannot be caught, blocked, or ignored) 

S I GXCP U 24 cpu time limit exceeded 

SIGXFSZ 25 file size limit exceeded 

S I GCONT 29» continue after stop (cannot be blocked) 

The following signals are also defined: 

SIGTRAP 5* trace trap 

SIGIOT 6* abort 

SIGEMT 7* EMT instruction 

SIGBUS 10* bus error 

SIGSYS 12* bad argument to system call 

SIGPWR 19 power-fail restart 

SIGVTALRM 26 virtual time alarm (see setitimer(2)) 

S I GPROF 27 profiling timer alarm (see set it ime r(2)) 

SIGWINCH 28« window size change 

SIGURG 30» urgent condition present on socket 

S I Gl 3 1» I/O possible on a descriptor (see f cnt 1 (2)) 

The starred signals (*) in the list above cause a core image if not 
caught or ignored. 

The default action for a signal may be reinstated by setting 
sv_handler to SIG_DFL; this default is termination (with a 
core image for starred signals) except for signals marked with • or 
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f. Signals marked with • are discarded if the action is sig_dfl; 
signals marked with t cause the process to stop. If sv_handler 
is SIG_IGN, the signal is subsequently ignored, and pending in- 
stances of the signal are discarded. 

If a caught signal occurs during certain system calls, the call is 
normally restarted. The affected system calls are read(2) or 
write(2) on a slow device such as a terminal, but not a file. This 
behavior may be inhibited by setting the SA_INTERRUPT bit in 

sa_flags. 

After a f ork(2), the child inherits all signals, the signal mask, 
and the signal stack. 

execve(2) resets all caught signals to default action and resets all 
signals to be caught on the user stack. Ignored signals remain ig- 
nored; the signal mask remains the same. 

RETURN VALUE 

On successful completion, a value of is returned. Otherwise, a 
value of -1 is returned and errno is set to indicate the error. 

ERRORS 

If any of the following conditions occur, sigaction returns -1 
and sets errno to the corresponding value: 

[einval] The value of sig is not a valid signal 

number, or an attempt was made to sup- 
ply an action for a signal that cannot be 
caught or ignored. 

[efault ] act or oact is an invalid address. Or both 

are invalid addresses. 

SEE ALSO 

exec(2), kill(2), sigsetops(3P), sigprocmask(2P), 
sigsuspend(3P), sigvec(2). 
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NAME 



sign, lsign, 
function 



dsign — Fortran transfer-of-sign intrinsic 



SYNOPSIS 

integer i, j f k 
real rl , rl, r3 
double precision dpi, dpi, dp3 

*=isign(i, j) 
k=sign(i, j) 

r3=sign (rl , rl) 

dp3=ds i gn ( dpi , dpi ) 
dp3=sign (dpi , dpi ) 

DESCRIPTION 

isign returns the magnitude of its first argument with the sign of 
its second argument sign and dsign are its real and double- 
precision counterparts, respectively. The generic version is sign, 
which devolves to the appropriate type depending on its argu- 
ments. 
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NAME 

signal — specify what to do upon receipt of a signal 

SYNOPSIS 

#include <signal.h> 

int (* signal (sig , func) ) () 

int sig; 

void (*func) () ; 

DESCRIPTION 

signal allows the calling process to choose one of three ways in 
which it is possible to handle the receipt of a specific signal, sig 
specifies the signal and June specifies the choice. 

sig can be assigned any one of the following except SIGKILL: 



SIGHUP 


1 


hangup 


SIGINT 


2 


interrupt 


SIGQUIT 


3* 


quit 


SIGILL 


4* 


illegal instruction 


SIGTRAP 


5* 


trace trap 


SIGIOT 


6* 


IOT instruction 


SIGEMT 


7* 


EMT instruction 


SIGFPE 


8* 


floating point exception 


SIGKILL 


9 


kill (cannot be caught, blocked, or ignored) 


SIGBUS 


10* 


bus error 


SIGSEGV 


11* 


segmentation violation 


SIGSYS 


12* 


bad argument to system call 


SIGPIPE 


13 


write on a pipe with no one to read it 


SIGALRM 


14 


alarm clock 


SIGTERM 


15 


software termination signal 


SIGUSR1 


16 


user defined signal 1 


SIGUSR2 


17 


user defined signal 2 


SIGCLD 


18* 


child status has changed 


SIGPWR 


19 


power-fail restart 


SIGTSTP 


20f 


stop signal generated from keyboard 


SIGTTIN 


21f 


background read attempted from control terminal 


SIGTTOU 


22f 


background write attempted to control terminal 


SIGSTOP 


23f 


stop (cannot be caught, blocked, or ignored) 


SIGXCPU 


24 


cpu time limit exceeded 


SIGXFSZ 


25 


file size limit exceeded 


SIGVTALRM 


26 


virtual time alarm (see setitimer(2)) 


SIGPROF 


27 


profiling timer alarm (see setitimer(2)) 


SIGWINCH 


28* 


window size change 
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SIGCONT 29» continue after stop (cannot be blocked) 

S I GURG 30* urgent condition present on socket 

SIGIO 31» I/O is possible on a descriptor (see fcnt 1(2)) 

The starred signals in the above list cause a core image if not 
caught or ignored (see below). 

Signals marked with • are discarded if the action is SIGJDFL; 
signals marked with t cause the process to stop if the process is 
part of 4.2 job control. 

func is assigned one of three values: SIG_dfl, SIG_ign, or a 
Junction-address. The actions prescribed by these values are as 
follows: 

SIG_dfl - terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be 
terminated with the following consequences: 

All of the receiving process's open file descriptors will 
be closed. 

If the parent process of the receiving process is execut- 
ing a wait, it will be notified of the termination of the 
receiving process and the terminating signal's number 
will be made available to the parent process; see 
wait(2). 

If the parent process of the receiving process is not exe- 
cuting a wait, the receiving process will be 
transformed into a zombie process (see ex it (2) for 
definition of zombie process). 

The parent process ID of each of the receiving 
process's existing child processes and zombie processes 
will be set to 1. This means the initialization process 
(see int ro(2)) inherits each of these processes. 

Each attached shared memory segment is detached and 
the value of shm_nattach in the data structure asso- 
ciated with its shared memory identifier is decremented 
byl. 

For each semaphore for which the receiving process 
has set a semad j value (see semop(2)), that semad j 
value is added to the semval of the specified sema- 
phore. 



February, 1990 

Revision C 



signal(3) signal(3) 



If the process has a process, text, or data lock, an un- 
lock is performed (see plock(2)). 

An accounting record will be written on the accounting 
file if the system's accounting routine is enabled; see 
acct(2). 

If the receiving process's process ID, tty group ID, and 
process group ID are equal, the signal sighup will be 
sent to all of the processes mat have a process group ID 
equal to the process group ID of the receiving process. 

A "core image" will be made in the current working 
directory of the receiving process if sig is one for which 
an asterisk appears in the above list and the following 
conditions are met: 

The effective user ID and the real user ID of the 
receiving process are equal. 

An ordinary file named core exists and is writ- 
able or can be created. If the file must be created, 
it will have the following properties: 

a mode of 0666 modified by the file creation 
mask (see umask(2)) 

a file owner ID that is the same as the effec- 
tive user ID of the receiving process 

a file group ID that is the same as the effec- 
tive group ID of the receiving process 

SIG_IGN- ignore signal 

The signal sig is to be ignored. 

Note: The signal SIGKILL cannot be ignored. 

function-address - catch signal 

Upon receipt of the signal sig, the receiving process is to ex- 
ecute the signal-catching function pointed to by June. The 
signal number sig will be passed as the only argument to the 
signal-catching function. Additional arguments are passed to 
the signal-catching function for hardware-generated signals. 
Before entering the signal-catching function, the value of 
June for the caught signal will be set to SIG_DFL unless the 
signal is SIGILL, SIGTRAP, or SIGPWR. 
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Upon return from the signal-catching function, the receiving 
process will resume execution at the point it was interrupted. 

When a signal that is to be caught occurs during a read, a 
write, an open, or an ioctl system call on a slow dev- 
ice (like a terminal; but not a file), during a pause system 
call, or during a wait system call that does not return im- 
mediately due to the existence of a previously stopped or 
zombie process, the signal-catching function will be execut- 
ed and then the interrupted system call may return a -1 to the 
calling process with errno set to eintr. This behavior is 
the default for 5.2 systems and it may be modified by the 
setcompat(2) system call. 

Note: The signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal sig except for a pend- 
ing SIGKILL signal. 

RETURN VALUE 

Upon successful completion, signal returns the previous value 
offwtc for the specified signal sig. Otherwise, a value of -1 is re- 
turned and errno is set to indicate the error. 

ERRORS 

signal will fail if: 

[EINVAL] sig is an illegal signal number, including SIG- 

KILL. 

WARNINGS 

Two other signals that behave differently than the signals 
described above exist in this release of the system; they are: 

S I GCLD 18 death of a child (reset when caught) 
S IGPWR 19 power fail (not reset when caught) 

There is no guarantee that, in future releases of the UNIX system, 
these signals will continue to behave as described below; they are 
included only for compatibility with other versions of the UNIX 
system. Their use in new programs is strongly discouraged. 

For these signals,/unc is assigned one of three values: S I G_DF L, 
SIG_IGN, or a function-address. The actions prescribed by these 
values of are as follows: 
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SIG_DFL - ignore signal 

The signal is to be ignored. 

SIG_IGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the cal- 
ling process's child processes will not create zombie 
processes when they terminate; see exit(2). 

function-address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as 
that described above for June equal to function-address. The 
same is true if the signal is SIGCLD except, that while the 
process is executing the signal-catching function, any re- 
ceived SIGCLD signals will be queued and the signal- 
catching function will be continually reentered until the 
queue is empty. 

The SIGCLD affects two other system calls (wait(2), and 
exit(2)) in the following ways: 

wait If the func value of S IGCLD is set to SIG_IGN and 

a wait is executed, the wait will block until all of 
the calling process's child processes terminate; it 
will then return a value of -1 with errno set to 

ECHILD. 

exit If in the exiting process's parent process the func 

value of SIGCLD is set to SIG_IGN, the exiting 
process will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the 
pipeline the parent of the proceeding processes. A process that 
may be piped into in this manner (and thus become the parent of 
other processes) should take care not to set SIGCLD to be caught 

SEE ALSO 

kill(l), kill(2), pause(2), ptrace(2), setcompat(2), 
sigvec(2), wait(2), set42sig(3), setjmp(3C). 

BUGS 

If a repeated signal arrives before the last one can be reset, there is 
no chance to catch it. However, see the setcompat flag 

COMPAT_BSDSIGNALS. 

The type specification of the routine and its func argument are 
problematical. 
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The symbols sighnd and sigtrap are globally defined sym- 
bols used by signal and are reserved words. 
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NAME 

signal — specify Fortran action on receipt of a system signal 

SYNOPSIS 

integer i 

external integer intfnc 

call signal (i, intfnc) 

DESCRIPTION 

signal allows a process to specify a function to be invoked 
upon receipt of a specific signal. The first argument specifies a 
fault or exception; the second argument specifies the function to 
be invoked. 

SEE ALSO 

kill(2), signal(3). 
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NAME 

sigprocmask — examine and change blocked signals 

SYNOPSIS 

tinclude <signal.h> 

int sigprocmask (how, set, oset) 

int how; 

sigset_t *set, oset; 

DESCRIPTION 

sigprocmask allows the calling process to examine or change 
its signal mask. If the value of set is not NULL, it points to a set 
of signals to be used to change the currently blocked set 

The value of how indicates the manner in which the set is 
changed. The permitted values for how are: 

SIG_block The resulting set will be the union of the 

current set and the signal set pointed to 
by set . 

SIG_unblock The resulting set will be the intersection 

of the current set and the complement of 
the signal set pointed to by set . 

SIG_SETMASK The resulting set will be the signal set 

pointed to by set . 

If oset is not NULL, the previous mask is stored at the location 
pointed to by set. If the value of set is NULL, the value of how is 
ignored and the process's signal mask is unchanged. When set is 
NULL, sigprocmask can be used to enquire about currently 
blocked signals. 

If there are any pending unblocked signals after the call to sig- 
procmask, at least one of those signals will be delivered before 
sigprocmask returns. 

S I GKI ll and S I GS TOP cannot be caught or ignored. S I GCONT 
cannot be ignored. It is not possible to block these signals. This is 
silently enforced. 

RETURN VALUE 

Upon successful completion, is returned. Otherwise, -1 is re- 
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turned and errno is set to indicate the error. 

ERRORS 

If the following condition occurs, sigprocmask will return -1 
and set errno to the corresponding value. 

[ E I nval ] The value of how is invalid. 

SEE ALSO 

sigaction(3P), sigpending(3P), sigsetops(3P), 
sigsuspend(3P). 
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NAME 

sigset jmp, siglongjmp — non-local jumps 

SYNOPSIS 

♦include <setjmp.h> 

int sigset jmp (env, savemask) 
sigjmp_buf env; 
int savemask; 

void siglongjmp {env, val) 
sigjmp_buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts 
encountered in a low-level subroutine of a program. 

sigset jmp saves its stack environment in env for later use by 
siglongjmp. If the value of savemask is not zero, sig- 
set jmp also saves the process's current signal mask as part of 
the calling environment. The environment type sig jmp_buf is 
defined in the <set jmp . h> header file. 

siglongjmp restores the environment saved by the last call of 
sigset jmp with the corresponding env argument. If env was 
initialized by a call to sigset jmp with a non-zero value for 
savemask, siglongjmp also restores the saved signal mask. 

RETURN VALUE 

When sigset jmp has been invoked by the calling process, zero 
is returned. 

After siglongjmp is completed, program execution continues 
as if the corresponding call of sigset jmp (which must not itself 
have returned in the interim) had just returned the value val. 
siglongjmp cannot cause sigset jmp to return the value 
zero. If val is zero, sigset jmp returns 1. All accessible data 
have values as of the time siglongjmp was called. 

WARNINGS 

siglongjmp fails if env was never initialized by a call to sig- 
set jmp or when the last such call is in a function which has 
since returned. 



February, 1990 

Revision C 



sigset jmp(3P) sigset jmp(3P) 



SEE ALSO 

sigaction(3P), sigprocmask(3P), sigsuspend(3P). 



February, 1990 

Revision C 



sigsetops(3P) 



sigsetops(3P) 



NAME 

sigaddset, sigdelset, sigismember, sigfillset, 
siginitset — manipulate signal sets 

SYNOPSIS 

♦include <signal.h> 

int sigaddset (set, signo) 
sigset_t *set; 
int signo; 

int sigdelset (set, signo) 
sigset_t *set; 
int signo; 

int s i gi smembe r ( set, signo ) 
sigset_t *set; 
int signo; 

int sigfillset (set) 
sigset_t *set; 

int sigemptyset (set) 
sigset_t *set; 

DESCRIPTION 

These routines manipulate sets of signals. They operate on data 
objects addressable by the application, not on any set of signals 
known to the system. The signal set modified by these rountines 
may be used as a parameter to sigagction(3P), 
sigprocmask(3P), sigpending(3P), or 

sigsispend(3P). sigaddset adds the signal 
specified by pointed to by set. 

sigdelset deletes the signal specified by signo from the set 
pointed to by set . 

POSIX defines the following signals: 



SIGABRT 

SIGALRM 

SIGFPE 

SIGHUP 

SIGILL 

SIGINT 

SIGKILL 



SIGPIPE 
SIGQUIT 
SIGSEGV 
SIGTERM 
SIGUSR1 
SIGUSR2 



SIGCLD 

SIGCONT 

SIGSTOP 

SIGTSTP 

SIGTTIN 

SIGTTOU 
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sigf illset initializes the signal set pointed to by set so that all 
POSIX-defined signals are included. 

sigemptyset initializes the signal set pointed to by set so that 
all the POSIX-defined signals are excluded. Applications must 
call sigemptyset for each object of type sigset_t before 
any other use of the object 

sigismember tests whether the signal specified by signo is a 
member of the set pointed to by set. 

RETURN VALUE 

On successful completion, sigismember returns 1 if the 
specified signal is a member of the specified set and returns if it 
is not On successful completion, each of the other functions re- 
turns 0. For all the functions listed, if an error is detected, 
sigaddset, sigdelset, and sigismember returns -1 and 
set errno to indicate the error. 

ERRORS 

If any of the following conditions occur, the function returns -1 
and sets errno to the corresponding value: 

[EINVAL] The value of signo is not a valid signal 

number. 

[ efault ] set is an invalid address. 

SEE ALSO 

sigaction(3P), sigpending(3P), sigprocmask(2P), 
sigsuspend(3P). 
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NAME 

sigsuspend — wait for a signal 

SYNOPSIS 

♦include <signal.h> 

int sigsuspend (sigmask) 
sigset_t *sigmask; 

DESCRIPTION 

sigsuspend replaces the process's signal mask with the set of 
signals pointed to by sigmask and then suspends the process un- 
til delivery of a signal whose action is either to execute a signal- 
catching function or to terminate the process. 

If the action is to terminate the process, sigsuspend will not re- 
turn. If the action is to execute a signal-catching function, sig- 
suspend will return after the signal-catching function returns, 
with the signal mask restored to the set that existed prior to the 
sigsuspend call. 

S I GKI LL and S I GS TOP cannot be caught or ignored. S I GCONT 
cannot be ignored. It is not possible to block these signals. This is 
silently enforced. 

RETURN VALUE 

Since sigsuspend suspends process execution indefinitely, 
there is no successful completion return value. If sigsuspend 
returns, it will return -1 and errno will be set to indicate the er- 
ror. 

ERRORS 

If the following condition occurs, sigsuspend will return -1 
and set errno to the corresponding value. 

[EINTR] A signal is caught by the calling process 

and control is returned from the signal- 
catching function. 

SEE ALSO 

pause(2), sigaction(3P), sigpending(3P), 
sigprocmask(2P), sigsetops(3P). 
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NAME 

sin, dsin, csin — Fortran sine intrinsic function 

SYNOPSIS 

real rl , r2 

double precision dpi, dp2 

complex cxl , cx2 

r2=sin(rl) 

dp2=ds in (dpi) 
dp2= sin (dpi) 

cx2=csin(cxl) 
cx2=s±n(cxl) 

DESCRIPTION 

sin returns the real sine of its real argument, dsin returns the 
double-precision sine of its double-precision argument, csin re- 
turns the complex sine of its complex argument. The generic sin 
function becomes dsin or csin as required by argument type. 

SEE ALSO 

trig(3M). 
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NAME 

s inh, ds inh — Fortran hyperbolic sine intrinsic function 

SYNOPSIS 

real rl , r2 

double precision dpi, dp2 

r2=sinh (rl) 

dp2=ds inh (dpi) 
dp2= sinh (dpi) 

DESCRIPTION 

sinh returns the real hyperbolic sine of its real argument, 
dsinh returns the double-precision hyperbolic sine of its 
double-precision argument. The generic form sinh may be used 
to return a double-precision value given a double-precision argu- 
ment. 

SEE ALSO 

sinh(3M). 
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NAME 

sinh, cosh, tanh — hyperbolic functions 

SYNOPSIS 

♦include <math.h> 

double sinh (x) 
double jc; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 

DESCRIPTION 

sinh, cosh, and tanh return, respectively, the hyperbolic sine, 
cosine, and tangent of their argument. 

RETURN VALUE 

sinh and cosh return HUGE (and sinh may return -HUGE for 
negative x) when the correct value would overflow and set errno 

to ERANGE . 

These error-handling procedures may be changed with the func- 
tion matherr(3M). 

SEE ALSO 

matherr(3M). 
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NAME 

sleep — suspend execution for interval 

SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

sleep suspends the current process from execution for the 
number of seconds specified by the argument The actual suspen- 
sion time may be less than that requested for two reasons: (1) 
scheduled wakeups occur at fixed 1-second intervals, (on the 
second, according to an internal clock) and (2) any caught signal 
will terminate sleep following execution of the signal catching 
routine. The suspension time may be longer than requested by an 
arbitrary amount, due to the scheduling of other activity in the sys- 
tem. The value returned by sleep is the "unslept" amount (the 
requested time minus the time actually slept) in case the caller had 
an alarm set to go off earlier than the end of the requested sleep 
time or in case there is premature arousal due to another caught 
signal. 

The routine is implemented by setting an alarm signal and pausing 
until it (or some other signal) occurs. The previous state of the 
alarm signal is saved and restored. The calling program may have 
set up an alarm signal before calling sleep. If the sleep time 
exceeds the time before the alarm signal, the process sleeps only 
until the alarm signal would have occurred and the caller's alarm 
catch routine is executed just before the sleep routine returns. If 
the sleep time is less than the time before the calling program's 
alarm, the prior alarm time is reset to go off at the same time it 
would have without the intervening sleep. 

SEE ALSO 

alarm(2), pause(2), signal(3). 
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NAME 

slots — ROM library functions 

SYNOPSIS 

cc [flags] files -lslots [libraries] 

DESCRIPTION 

The routines in the slots library provide access to board slot ROM 
from either user or kernel processes. Calls to library routines do 
not require knowledge of either the board ROM configuration or 
the ROM addressing requirements. 

USER FUNCTIONS 

slot_PRAM_init (slot, data) 

Read the PRAM ink structure for slot into the buffer pointed 
to by data. 

slot_board_f lags (slot) 

Read and return the board flags for slot. 

slot_board_id (slot) 

Read and return the board ID number for slot. 

slot_board_name (slot, data, size) 

Read up to size bytes of the board name string for slot into 
the buffer pointed to by data. 

slot_board_type (slot, data) 

Read and return the unsigned 64 bit or 8 byte board type for 
slot into the buffer pointed to by data. 

slot_ether_addr (slot, data) 

For slot read 6 bytes of ethemet address into the buffer point- 
ed to by data. 

slot_primary_init (slot, data) 

For slot read the primary init structure into the buffer pointed 
to by data. 

slot_jpart_num (slot, data, size) 

For slot get size bytes of the part number string into the 
buffer pointed to by data. 

slot_rev_level (slot, data, size) 

For slot get size bytes of the revision level of the ROM into 
the buffer pointed to by data. 

slot_serial_number (slot, data, size) 

For slot get size bytes of serial number string into the buffer 
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pointed to by data. 

slot_vendor_id (slot, data, size) 

For slot read size bytes of vendor ID string into the buffer 
pointed to by data. 

UTILITY FUNCTIONS 

slot_board_vendor_inf o (kind, slot, data, size) 

For slot get size bytes of the vendor information string of 
type kind into the buffer pointed to by data. 

slot_byte (address) 

Return the byte located at address. 

slot_data (slot, land, request, data, size) 

For slotloU read size BITS of data for resource of type kind 
from the resource list item of type request and put it into the 
location pointed to by data. 

slot_di rectory (slot, data, size) 

For slot read the resource directory into the buffer of size en- 
tries pointed to by data. 

slot_long (address, data) 

Return 32 bits of data from address offset by data. 

slot _re source (address, kind, request, data, size) 
For ROM starting at base address read size bytes of the re- 
quest resource item from the kind resource into the buffer 
pointed to by data. 

slot_resource_list (address, land, data, size) 

For ROM starting at base address read size entries of 
resource list of kind into the buffer pointed to by data. 

slot_structure (address, from, data, size) 

From ROM starting at address plus the offset in parameter 
from read size bytes of data into the buffer pointed to by data. 

slot_word (address) 

Return 16 bits of data located at address. 

LOW LEVEL FUNCTIONS 

slot_seg_violation ( ) 

This routine is passed to slot_catch to handle bus errors. 

slot_catch (kind, routine) 

Setup routine to handle interrupts of type kind. 
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slot_ignore (kind) 

Return the system to default handling of interrupts of type 
land. 

slot_address (slot) 

Returns a computed ROM base address for slot. 

slot_bytelane (address, bytelane) 

Return the ROM bytelane byle into bytelane for ROM start- 
ing at address. 

slot_calc_pointer (current, offset) 

Return a ROM pointer offset bytes from current. 

slot_rom_data (address, width, data) 

Starting with address fill the buffer pointed to by data with 
width bytes of data. 

slot_check_crc (top, fhp, bytelane) 

Check the CRC for the ROM with base address top using the 
format header information pointed to by fhp and the byte lane 
information in bytelane. 

slot_header (address, formatjidrp) 

Read the ROM format header into the buffer pointed to by 
formatjidrp for the ROM starting at base address address. 

SEE ALSO 

Building AJUX Device Drivers 

NOTE 

The slots library is only accessible to processes with superuser 
privileges due to the required phys call to access board ROM. 
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NAME 

spray — scatter data in order to check the network 

SYNOPSIS 

#include <rpcsvc/spray.h> 

DESCRIPTION 
RFC INFO 

Program number: sprayprog 

xdr routines: 

xdr_sprayarr (xdrs, arr) ; 

XDR *xdrs; 

struct sprayarr *arr; 
xdr_spraycumul (xdrs, cumul) ; 

XDR *xdrs; 

struct spraycumul * cumul; 

Procs: 

SPRAYPROC_SPRAY 

Takes no arguments; returns no value. Increments a counter 
in server daemon. The server does not return this call, so the 
caller should have a timeout of 0. 

SPRAYPROC_GET 

Takes no arguments; returns structure spraycumul with 
value of counter and clock. 

SPRAYPROC_CLEAR 

Takes no arguments and returns no value. Zeros out counter 
and clock. 

Versions: 

SPRAYVERS_ORIG 

Structures: 

struct spraycumul { 
unsigned counter; 
struct timeval clock; 

>; 

struct sprayarr { 

int *data, 

int lnth 
}; 
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SEE ALSO 

spray(lM), sprayd(lM). 



February, 1990 
Revision C 



sputl(3X) sputl(3X) 



NAME 

sputl, sgetl — access long integer data in a machine 
independent fashion 

SYNOPSIS 

void sputl {value, buffer) 
long value; 
char * buffer; 

long sgetl (buffer) 
char *buffer; 

DESCRIPTION 

sputl takes the 4 bytes of the long integer value and places them 
in memory, starting at the address pointed to by buffer. The order- 
ing of the bytes is the same across all machines. 

sgetl retrieves the 4 bytes in memory, starting at the address 
pointed to by buffer, and returns the long integer value in the byte 
ordering of the host machine. 

Use of sputl and sgetl provide a machine independent way of 
storing long numeric data in a file in binary form without conver- 
sion to characters. 

A program that uses these functions must be loaded with the ob- 
ject file access routine library 1 ibid. a. 

SEE ALSO 

ar(4). 
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NAME 

sqrt, dsqrt, csqrt — Fortran square root intrinsic function 

SYNOPSIS 

real rl , r2 

double precision dpi, dpi 

complex cxl, cx2 

r2=sqrt (rl) 

dp2=dsqrt (dpi ) 
dp2=sqrt (dpi) 

c*2=csqrt (cxl) 
cx2=sqrt (cxl) 

DESCRIPTION 

sqrt returns the real square root of its real argument, dsqrt re- 
turns the double-precision square root of its double-precision ar- 
gument csqrt returns the complex square root of its complex 
argument, sqrt, the generic form, will become dsqrt or 
csqrt as required by its argument type. 

SEE ALSO 

exp(3M). 
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NAME 

ssignal, gsignal — software signals 

SYNOPSIS 

♦include <signal.h> 

int (*ssignal {sig, action)) () 
int sig, (* action) () ; 

int gsignal (sig) 
int sig; 

DESCRIPTION 

ssignal and gsignal implement a software facility similar to 
signal(3). This facility is used by the Standard C Library to en- 
able users to indicate the disposition of error conditions; it is also 
made available to users for their own purposes. 

Software signals made available to users are associated with in- 
tegers in the inclusive range 1 through 15. A call to ssignal as- 
sociates a procedure, action, with the software signal, sig; the 
software signal, sig, is raised by a call to gsignal. Raising a 
software signal causes the action established for that signal to be 
taken. 

The first argument to ssignal is a number identifying the type 
of signal for which an action is to be established. The second ar- 
gument defines the action; it is either the name of a user-defined 
action function or one of the manifest constants SIG_DFL (de- 
fault) or SIG_IGN (ignore), ssignal returns the action previ- 
ously established for that signal type; if no action has been esta- 
blished or the signal number (sig) is illegal, ssignal returns 
SIG_DFL. 

gsignal raises the signal identified by its argument, sig: 

If an action function has been established for sig, then that 
action is reset to SIG_DFL and the action function is en- 
tered with argument sig. gsignal returns the value re- 
turned to it by the action function. 

If the action for sig is SIG_IGN, gsignal returns the 
value 1 and takes no other action. 

If the action for sig is SIG_DFL, gsignal returns the 
value and takes no other action. 
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If sig has an illegal value or no action was ever specified for 
sig, gsignal returns the value and takes no other action. 

SEE ALSO 

sigvec(2), signal(3). 

NOTES 

There are some additional signals with numbers outside the range 
1 through 15 which are used by the Standard C Library to indicate 
error conditions. Thus, some signal numbers outside the range 1 
through 15 are legal, although their use may interfere with the 
operation of the Standard C Library. 
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NAME 

strcat, strncat, strcmp, strncmp, strcpy, 
strncpy, strlen, strchr, strrchr, strpbrk, 
strspn, strcspn, strtok — string operations 

SYNOPSIS 

#include <string.h> 

char *strcat(.s7, s2) 
char *sl, *s2; 

char *strncat (si, s2, n) 
char *sl, *s2; 
int n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *strcpy(.y7, s2) 
char *sl, *s2; 

char *strncpy ($7, s2, n) 
char *sl, *s2; 
int n; 

int strlen (s) 
char *s; 

char *strchr(.y, c) 
char *s; 
int c; 

char *strrchr(.s, c) 
char *s; 
int c; 

char *strpbrk(&7, s2) 
char *.s7, *j2; 

int strspn (si, s2) 
char *,s7, *s2; 

int strcspn ($7, s2) 
char *sl, *s2; 
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char *strtok (sl,s2) 
char *sl, *s2; 

DESCRIPTION 

The arguments si, s2, and s point to strings (arrays of characters 
terminated by a null character). The functions strcat, 
stmcat, strcpy, and strncpy all alter si. These functions 
do not check for overflow of the array pointed to by si. 

strcat appends a copy of string s2 to the end of string si. 
stmcat appends at most n characters. Each function returns a 
pointer to the null-terminated result 

strcmp performs a lexicographical comparison of its arguments 
and returns an integer less than, equal to, or greater than 0, when 
si is less than, equal to, or greater than s2, respectively. 
strncmp makes the same comparison but looks at a maximum of 
n characters. 

strcpy copies string s2 to string si, stopping after the null char- 
acter has been copied, strncpy copies exactly n characters, 
truncating s2 or adding null characters to si if necessary. The 
result is not null-terminated if the length of s2 is n or more. Each 
function returns si. 

strlen returns the number of characters in s, not including the 
terminating null character. 

strchr (strrchr) returns a pointer to the first (last) oc- 
currence of character c in string s, or a NULL pointer if c does not 
occur in the string. The null character terminating a string is con- 
sidered to be part of the string. 

strpbrk returns a pointer to the first occurrence in string si of 
any character from string s2, or a NULL pointer if no character 
from s2 exists in si. 

strspn (strcspn) returns the length of the initial segment of 
string si which consists entirely of characters from (not from) 
string s2. 

st rtok considers the string si to consist of a sequence of zero or 
more text tokens separated by spans of one or more characters 
from the separator string s2. The first call (with pointer si 
specified) returns a pointer to the first character of the first token, 
and writes a null character into si immediately following the re- 
turned token. The function keeps track of its position in the string 
between separate calls, so that on subsequent calls (which must be 
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made with a NULL pointer as the first argument) it works through 
the string si immediately following that token. This can be con- 
tinued until no tokens remain. The separator string s2 may be dif- 
ferent from call to call. When no token remains in si, a NULL 
pointer is returned. 

NOTES 

For user convenience, some of these functions are declared in the 
optional <st ring . h> header file. 

BUGS 

strcmp uses native character comparison. Thus the sign of the 
value returned when one of the characters has its high-order bit set 
is implementation-dependent 

All string movement is performed character by character starting 
at the left. Thus overlapping moves toward the left will work as 
expected, but overlapping moves to the right may yield surprises. 
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NAME 

strtod — convert string to double-precision number 

SYNOPSIS 

double strtod (str, ptr) 
char *str r **ptr; 

DESCRIPTION 

strtod returns as a double-precision floating-point number, the 
value represented by the character string pointed to by str. The 
string is scanned up to the first unrecognized character. 

strtod recognizes an optional string of "white-space" charac- 
ters (as defined by is space in ctype(3Q), then an optional 
sign, then a string of digits optionally containing a decimal point, 
then an optional e or E followed by an optional sign or space, fol- 
lowed by an integer. 

If the value of ptr is not ( char * * ) null, a pointer to the char- 
acter terminating the scan is returned in the location pointed to by 
ptr. If no number can be formed, *ptr is set to str, and zero is re- 
turned. 

SEE ALSO 

bstring(3), atof(3C), ctype(3C), memcpy(3C), 
scanf(3S), string(3C). strtol(3Q. 

DIAGNOSTICS 

If the correct value would cause overflow, ±HUGE is returned (ac- 
cording to the sign of the value), and errno is set to ERANGE. 
If the correct value would cause underflow, zero is returned and 
errno is set to ERANGE. 
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NAME 

strtol, atol, atoi — convert string to integer 

SYNOPSIS 

long st rtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

strtol returns as a long integer the value represented by the 
character string pointed to by str. The string is scanned up to the 
first character inconsistent with the base. Leading white-space 
characters (blanks and tabs) are ignored. 

If the value of ptr is not ( char * * ) null, a pointer to the char- 
acter terminating the scan is returned in the location pointed to by 
ptr. If no integer can be formed, zero is returned. 

If base is positive (and not greater than 36), it is used as the base 
for conversion. After an optional leading sign, leading zeros are 
ignored; a leading Ox or Ox is ignored if base is 16. 

If base is zero, the string itself determines the base. After an op- 
tional leading sign, a leading zero indicates octal conversion and a 
leading Ox or OX indicates hexadecimal conversion; otherwise, de- 
cimal conversion is used. 

Truncation from long to int can take place upon assignment or 
by an explicit cast. 

atol (str) is equivalent to: 

strtol (str, (char **)NULL, 10) 
atoi (str) is equivalent to: 

(int) strtol (str, (char **)NULL, 10) 

SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 
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BUGS 

Overflow conditions are ignored. 
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NAME 

swab — swap bytes 

SYNOPSIS 

void swab {from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

swab copies nbytes bytes referenced by from to the array refer- 
enced by to, exchanging adjacent even and odd bytes. It is useful 
for carrying binary data between PDP-lls and other machines. 
nbytes should be even and non-negative. If nbytes is odd and po- 
sitive, swab uses nbytes-l instead. If nbytes is negative, swab 
does nothing. 
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NAME 

sysconf — get configurable system variables 

SYNOPSIS 

♦include <unistd.h> 

long sysconf (name) 
int name; 

DESCRIPTION 

sysconf allows an application to determine the current value of 
a configurable system variable. 

name represents the system variable to be queried. Allowable 
values for name are: 

_SC_ARG_MAX 

_SC_CHILD_MAX 

_SC_CLK_TCK 

_SC_NGROUP S_MAX 

_SC_OPEN_MAX 

_SC_PASS_MAX 

_SC_PID_MAX 

_SC_UID_MAX 

_SC_EXIT_SIGHUP 

_SC_JOB_CONTROL 

_SC_KI LL_P ID_NEG1 

_SC_KILL_SAVED 

_SC_PGID_CLEAR 

_SC_SAVED_IDS 

_SC_VERSION 

RETURN VALUE 

sysconf returns the current value of the specified variable. The 
value returned will not be more restrictive than the value 
described to the application when it was compiled with 
<limits . h> or <unistd. h>. The value will not change dur- 
ing the lifetime of the calling process. 

ERRORS 

If name is not defined on the system or name is invalid, sysconf 
will return -1. 
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SEE ALSO 

pathconf(3P). 
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NAME 

system — issue a shell command from Fortran 

SYNOPSIS 

character *N c 

call system (c) 

DESCRIPTION 

system causes its character argument to be given to sh(l) as in- 
put, as if the string had been typed at a terminal. The current pro- 
cess waits until the shell has completed. 

SEE ALSO 

sh(l), exec(2), system(3S). 
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NAME 

system — issue a shell command 

SYNOPSIS 

♦include <stdio.h> 

int system( string ) 
char *string; 

DESCRIPTION 

system causes string to be given to sh(l) input, as if the string 
had been typed as a command at a terminal. The current process 
waits until the shell has completed and then returns the exit status 
of the shell. 

RETURN VALUE 

system forks to create a child process that in turn performs 
exec(2) on /bin/sh in order to execute string. If fork or 
exec fails, system returns a negative value and sets errno. If 
fork and exec succeed, the exit status of the shell is returned. 

FILES 

/bin/sh 

SEE ALSO 

sh(l), exec(2). 
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NAME 

tan, dt an — Fortran tangent intrinsic function 

SYNOPSIS 

real rl , r2 

double precision dpi, dp2 

r2=tan(rl) 

dp2=dt an (dpi) 
dp2= f tan (dpi) 

DESCRIPTION 

tan returns the real tangent of its real argument, dtan returns 
the double-precision tangent of its double-precision argument 
The generic tan function becomes dtan as required with a 
double-precision argument 

SEE ALSO 

trig(3M). 
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NAME 

tanh, dtanh — Fortran hyperbolic tangent intrinsic function 

SYNOPSIS 

real rl , r2 

double precision dpi, dp2 

r2=tanh(rl) 

dp2=dtanh(dpl) 
dp2=t anh (dpi) 

DESCRIPTION 

tanh returns the real hyperbolic tangent of its real argument 
dtanh returns the double-precision hyperbolic tangent of its dou- 
ble precision argument. The generic form tanh may be used to 
return a double-precision value given a double-precision argu- 
ment. 

SEE ALSO 

sinh(3M). 
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NAME 

tcdrain, tcflow, tcflush, tcsendbreak — line 
control functions 

SYNOPSIS 

#include <termios.h> 

int tcdrain (fildes) 
int fildes; 

int tcflow {fildes , action) 
int fildes, action; 

int tcflush {fildes , queue _selector ) 
int fildes, queue _selector; 

int tcsendbreak {fildes , duration) 
int fildes, duration; 

DESCRIPTION 

tcdrain causes the process to wait until all output written to the 
object indicated by fildes has been transmitted. 

tcflow will suspend transmission or reception of data on the ob- 
ject indicated by fildes, depending on the value of action. If ac- 
tion is TCOOFF, output will be suspended. If action is TCOON, 
suspended output will be restarted. If action is TCI OF, input will 
be suspended. If action is TCI ON, suspended input will be restart- 
ed. 

tcflush will discard data written to the object indicated by 
fildes but not transmitted, or data received but not read, depending 
on the value of queue _selector. If queue _selector is TCIFLUSH 
data received, but not read, will be flushed. If queue selector is 
TCOFLUSH data written, but not transmitted, will be flushed. If 
queue jelector is TCIOFLUSH both data received, but not read, 
and data written, but not transmitted, will be flushed. 

tcsendbreak will assert a break condition on the serial line as- 
sociated with fildes depending on the value of duration. If dura- 
tion is zero, the break condition will be asserted for 0.25 seconds. 
If duration is not zero, no break will be sent 

RETURN VALUE 

Upon successful completion, zero is returned. Otherwise, -1 is 
returned and errno is set to indicate the error. 
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ERRORS 

If any of the following conditions occur, -1 will be returned and 
errno will be set to the corresponding value. 

[ ebadf ] fildes is not a valid file descriptor. 

[EINVAL] The device does not support the function 

or if the function called was tcf lush, 
queue ^selector is invalid. 

[ enotty ] The file associated with fildes is not a ter- 

minal. 

In addition to those listed already, tcdrain will report the fol- 
lowing error. 

[EINTR] tcdrain was interrupted by a signal. 

SEE ALSO 

termios(7P). 
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NAME 

tcgetattr, tcsetatt r — get and set the terminal state 

SYNOPSIS 

♦include <termios.h> 

int tcgetattr (Jildes, termios-p) 

int Jildes; 

struct termio *termio-p; 

int tcsetat.tr {Jddes , optional-actions, termio-p) 
int jildes, optional-actions; 
struct termio * termio-p; 

DESCRIPTION 

tcgetattr retrieves the parameters associated with the device 
indicated by jildes and stores them in the termios structure indi- 
cated by termios-p. 

tcsetattr sets the parameters associated with the terminal us- 
ing the information in the termios structure pointed to by 
termios-p. The action taken is dependent on the value of 
optional-actions. If optional-actions is TCSANOW, the change oc- 
curs immediately. If optional-actions is tcsadrain, the change 
occurs after all output written to jildes has been transmitted. 
tcsadrain should be used when changing parameters that af- 
fect output. If optional-actions is TCSAFLUSH, the change occurs 
after all output written to the object indicated by jildes has been 
transmitted; all input that has been received but not read is dis- 
carded before the change is made. 

tcgettattr is allowed from a background process; however, 
the terminal attributes may be changed later by a foreground pro- 
cess. 

RETURN VALUE 

On successful completion, a value of is returned. Otherwise, -1 
is returned and errno is set to indicate the error. 

ERRORS 

If any of the following conditions occur, tcgetattr and 
tcsetattr return -1 and set errno to the corresponding 
value: 

[ ebadf ] The file descriptor jildes is not valid. 

[EINVAL] The device does not support the function 

called, or if the function called was 
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[ENOTTY] 



tcsetattr, optional-actions is an in- 
valid value. 

The file associated mlhfildes is not a ter- 
minal. 



SEE ALSO 

cf getospeed(3P), termios(7P). 
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NAME 

tcgetpgrp — get distinguished process group ID 

SYNOPSIS 

♦include <sys/ types. h> 

pid_t tcgetpgrp (fildes) 
int fildes; 

DESCRIPTION 

tcgetpgrp is part of the POSIX Job Control option. 

tcgetpgrp returns the value of the process group ID of the 
foreground process group associated with the terminal. 
tcgetpgrp may be called from a process that is a member of a 
background process group; however, the information may be sub- 
sequently changed by a process that is a member of a foreground 
process group. 

RETURN VALUE 

On successful completion, tcgetpgrp returns the process group 
ID of the foreground process group associated with the terminal. 
Otherwise, -1 is returned and errno is set to indicate the error. 

ERRORS 

If any of the following conditions occur, tcgetpgrp will return 
-1 and set errno to the corresponding value. 

[ ebadf ] The file descriptor fildes is not valid. 

[EINVAL] tcgetpgrp is not permitted for the 

device associated with fildes. 

[ENOTTY] The calling process does not have a con- 

trolling terminal, or the file is not the 
controlling terminal. 

SEE ALSO 

setsid(2P), setpgid(2P), tcsetpgrp(3P). 
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NAME 

tcsetpgrp — set distinguished process group ID 

SYNOPSIS 

♦include <sys/types.h> 

int tcsetpgrp {fildes f pgrp-id) 
int fildes; 
pid_t pgrp-id; 

DESCRIPTION 

tcsetpgrp is part of the POSIX Job Control Option. 

If the process has a controlling terminal, tcsetpgrp sets the dis- 
tinguished process group ID associated with the terminal to pgrp- 
id. The file associated with fildes must be the controlling terminal 
of the calling process, and the controlling terminal must be 
currently associated with the session of the calling process. The 
pgrp-id must match a process group ID of a process in the same 
session as the calling process. 

RETURN VALUE 

On successful completion, tcsetpgrp returns 0. Otherwise, -1 
is returned and errno is set to indicate the error. 

ERRORS 

[ ebadf ] The file descriptor fildes is not valid. 

[einval] tcsetpgrp is not permitted for the 

device associated with fildes, or the value 
of pgrp-id is less than or equal to or 
exceeds pid_max. 

[enotty] The calling process does not have a con- 

trolling terminal, or the file is not the 
controlling terminal. 

[eperm] pgrp-id is greater than and less than or 

equal to pid_max, and there is no pro- 
cess in the process group indicated by 
pgrp-id that has the same controlling ter- 
minal as the calling process. 

SEE ALSO 

setsid(2P), setpgid(2P), tcgetpgrp(3P). 
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NAME 

tgetent, tgetnum, tgetflag, tgetstr, tgoto, 
tputs — terminal independent operation routines 

SYNOPSIS 

char PC- 
char *BC; 
char *UP; 
short ospeed; 

int tgetent (bp, name) 
char *bp, *name; 

int tgetnum (irf) 
char *id; 

int tgetflag (/rf) 
char *id; 

char * tgetstr (id f area) 
char *id, **area; 

char *tgoto (cm, destcol, destline) 
char *cm; 
int destcol; 
int destline; 

int tputs (cp, affcnt, outc) 
char *cp; 
int affcnt; 
int (* outc) () ; 

DESCRIPTION 

These functions extract and use capabilities from the terminal ca- 
pability database termcap(4). Note that these are low-level rou- 
tines. 

tgetent extracts the entry for terminal name into the buffer at 
bp. bp should be a character buffer of size 1024 and must be re- 
tained through all subsequent calls to tgetnum, tgetflag, and 
tgetstr. tgetent returns -1 if it cannot open the termcap 
file, if the terminal name given does not have an entry, and 1 if 
successful. It looks in the environment for a TERMCAP variable. 
If a variable is found whose value does not begin with a slash and 
the terminal type name is the same as the environment string 
term, the termcap string is used instead of reading the 
termcap file. If the value does begin with a slash, the string is 
used as a pathname rather than /etc /termcap. This can speed 
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up entry into programs that call tgetent. It can also help debug 
new terminal descriptions or be used to make one for your termi- 
nal if you can't write the file /etc/termcap. 

tgetnum gets the numeric value of capability id, returning -1 if 
is not given for the terminal, tget f lag returns 1 if the specified 
capability is present in the terminal's entry, if it is not. 
tget st r gets the suing value of capability id, placing it in the 
buffer at area, advancing the area pointer. It decodes the abbrevi- 
ations for this field described in termcap(4), except for cursor 
addressing and padding information. 

tgoto returns a cursor addressing string decoded from cm to go 
to column destcol in line destline. It uses the external variables 
UP (from the up capability) and BC (if be is given rather than bs) 
if necessary to avoid placing \n, ~D, or ~@ in the returned string. 
(Programs that call tgoto should be sure to turn off the xtabs 
bit(s), since tgoto may now output a tab. Note that programs 
using termcap should in general turn off XTABS anyway since 
some terminals use Control-I for other functions, such as non- 
destructive space.) If a % sequence is given which is not under- 
stood, then tgoto returns "OOPS". 

tputs decodes the leading padding information of the string cp; 
af f cnt gives the number of lines affected by the operation, or 1 
if this is not applicable; outc is a routine that is called with each 
character in turn. The external variable o speed should contain 
the output speed of the terminal as encoded by stty ( 1 ) . The 
external variable PC should contain a pad character to be used 
(from the pc capability) if a null (* @) is inappropriate. 

FILES 

/lib/libtermcap . a 
/etc/termcap 

SEE ALSO 

ex(l), termcap(4). 
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NAME 

tmpf ile — create a temporary file 

SYNOPSIS 

♦include <stdio.h> 

FILE *tmpfile() 

DESCRIPTION 

tmpf ile creates a temporary file using a name generated by 
tmpnam(3S), and returns a corresponding file pointer. The file 
is automatically deleted when the process using it terminates. The 
file is opened for update ("w+"). tmpf ile calls f open and so 
returns any error code passed to it from f open. 

RETURN VALUE 

If the temporary file cannot be opened, an error message is printed 
using perror(3C), and a NULL pointer is returned. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), mktemp(3C), 
perror(3C), tmpnam(3S). 
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NAME 

tmpnam, tempnam — create a name for a temporary file 

SYNOPSIS 

#include <stdio.h> 

char *tmpnam(.s) 
char *s; 

char *tempnam(<flr, pfx) 
char *dir r *pfx; 

DESCRIPTION 

These functions generate filenames that can safely be used for a 
temporary file. 

tmpnam always generates a filename using the pathname defined 
as p_tmpdir in the <stdio.h> header file. If s is NULL, 
tmpnam leaves its result in an internal static area and returns a 
pointer to that area. The next call to tmpnam will destroy the 
contents of the area. If s is not NULL, it is assumed to be the ad- 
dress of an array of at least l_tmpnam bytes, where l_tmpnam 
is a constant defined in <stdio . h>; tmpnam places its result in 
that array and returns s. 

tempnam allows the user to control the choice of a directory. 
The argument dir points to the pathname of the directory in which 
the file is to be created. If dir is NULL or points to a string which 
is not a pathname for an appropriate directory, the pathname 
defined as p_tmpdir in the <stdio . h> header file is used. If 
that pathname is not accessible, /tmp will be used as a last resort. 
This entire sequence can be upstaged by providing an environ- 
ment variable tmpdir in the user's environment, whose value is 
a pathname for the desired temporary-file directory. 

Many applications prefer that names of temporary files contain 
favorite initial letter sequences. Use the pfx argument for this. 
This argument may be NULL or point to a string of up to 5 char- 
acters to be used as the first few characters of the name of the tem- 
porary file. 

tempnam uses malloc(3C) to get space for the constructed 
filename and returns a pointer to this area. Thus, any pointer 
value returned from tempnam may serve as an argument \ofree 
(see malloc(3C)). If tempnam cannot return the expected 
result for any reason (i.e., ma Hoc failed or attempts to find an 
appropriate directory were unsuccessful), a NULL pointer will be 
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returned. 

NOTES 

These functions generate a different filename each time they are 
called. 

Files created using these functions and either f open(3S) or 
creat(2) are temporary only in the sense that they reside in a 
directory intended for temporary use and their names are unique. 
It is the user's responsibility to use unlink(2) to remove the file 
when its use is ended. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), 
mktemp(3C), tmpfile(3S). 

BUGS 

If called more than 17,576 times in a single process, tmpnam and 
tempnam will start recycling previously used names. 
Between the time a filename is created and the file is opened, it is 
possible for some other process to create a file with the same 
name. This can never happen if that other process is using 
tmpnam, tempnam, or mktemp(3C) and the filenames are 
chosen carefully to avoid duplication by other means. 
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NAME 

sin, cos, tan, asin, acos, atan, atan2 — 
trigonometric functions 

SYNOPSIS 

#include <math.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double re- 
double asin (x) 
double re- 
double acos (x) 
double re- 
double atan (x) 
double re- 
double atan2 (y, x) 
double x, y; 

DESCRIPTION 

sin, cos, and tan return, respectively, the sine, cosine, and 
tangent of their argument, which is in radians. 

asin returns the arcsine of rr, in the range -tc/2 to tc/2. 

acos returns the arccosine of *, in the range to n. 

atan returns the arctangent of re, in the range -tc/2 to tc/2. 

atan2 returns the arctangent of y/x, in the range -n to tc, using 
the signs of both arguments to determine the quadrant of the return 
value. 

RETURN VALUE 

sin, cos, and tan lose accuracy when their argument is far 
from zero. For arguments sufficiently large, these functions return 
when there would otherwise be a complete loss of significance. 
In this case a message indicating TLOSS error is printed on the 
standard error output For less extreme arguments, a P LOSS error 
is generated but no message is printed. In both cases, errno is 

set to ERANGE. 
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If the magnitude of the argument ofasinoracosis greater than 
one, or if both arguments of atan2 are zero, zero is returned and 
errno is set to EDOM. In addition, a message indicating domain 
error is printed on the standard error output. 

These error-handling procedures may be changed with the func- 
tion matherr(3M). 

SEE ALSO 

matherr(3M). 
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NAME 

tsearch, tfind, tdelete, twalk — manage binary 
search trees 

SYNOPSIS 

♦include <search.h> 

char *tsearch(£ey, rootp, compar) 
char *key; 
char **rootp; 
int (* compar) () ; 

char *tfind(£ey, rootp, compar); 
char *key; 
char **rootp; 
int (* compar) () ; 

char * tdelete (key, rootp, compar); 
char *key; 
char ** rootp; 
int (* compar) () ; 

void twalk (roof, action) 
char *roof; 
void(*acft"on) () ; 

DESCRIPTION 

tsearch, tfind, tdelete, and twalk are routines for mani- 
pulating binary search trees. They are generalized from Knuth 
(6.2.2) Algorithms T and D. All comparisons are done with a 
user-supplied routine. This routine is called with two arguments, 
the pointers to the elements being compared. It returns an integer 
less than, equal to, or greater than 0, according to whether the first 
argument is to be considered less than, equal to or greater than the 
second argument The comparison function need not compare 
every byte, so arbitrary data may be contained in the elements in 
addition to the values being compared. 

tsearch is used to build and access the tree, key is a pointer to 
a datum to be accessed or stored. If there is a datum in the tree 
equal to *key (the value referenced by key), a pointer to this found 
datum is returned. Otherwise, *key is inserted, and a pointer to it 
returned. Only pointers are copied, so the calling routine must 
store the data, rootp points to a variable that points to the root of 
the tree. A NULL value for the variable referenced by rootp 
denotes an empty tree; in this case, the variable will be set to point 



February, 1990 

Revision C 



tsearch(3C) tsearch(3C) 



to the datum which will be at the root of the new tree. 

Like t search, t find will search for a datum in the tree, return- 
ing a pointer to it if found. However, if it is not found, tf ind 
will return a NULL pointer. The arguments for tf ind are the 
same as for t search. 

t delete deletes a node from a binary search tree. The argu- 
ments are the same as for t search. The variable pointed to by 
rootp will be changed if the deleted node was the root of the tree, 
tdelete returns a pointer to the parent of the deleted node, or a 
NULL pointer if the node is not found. 

twalk traverses a binary search tree, root is the root of the tree 
to be traversed. (Any node in a tree may be used as the root for a 
walk below that node.) action is the name of a routine to be in- 
voked at each node. This routine is, in turn, called with three ar- 
guments. The first argument is the address of the node being visit- 
ed. The second argument is a value from an enumeration data 
type 

typedef enum {preorder,postorder,endorder, leaf } VISIT; 

(defined in the <search.h> header file), depending on whether 
mis is the first, second or third time that the node has been visited 
(during a depth-first, left-to-right traversal of the tree), or whether 
the node is a leaf. The third argument is the level of the node in 
the tree, with the root being level zero. 

The pointers to the key and the root of the tree should be of type 
pointer-to-element, and cast to type pointer-to-character. Similar- 
ly, although declared as type pointer-to-character, the value re- 
turned should be cast into type pointer-to-element. 

EXAMPLES 

The following code reads in strings and stores structures contain- 
ing a pointer to each string and a count of its length. It then walks 
the tree, printing out the stored strings and their lengths in alpha- 
betical order. 

#include <search.h> 
tinclude <stdio.h> 

struct node { /*pointers to these are 

char * string; stored in the tree*/ 
int length; 

}; 
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char string_space [10000] ; /*space to store 

strings*/ 
struct node nodes[500]; /*nodes to store*/ 
struct node *root = NULL; /*this points to the 

root*/ 

main( ) 
{ 

char *strptr = string_space; 

struct node *nodeptr = nodes; 

void print_node ( ) , twalk ( ) ; 

int i = 0, node_compare ( ); 

while (gets (strptr) != NULL && i++ < 500) { 
/* set node */ 
nodeptr— >string = strptr; 
nodeptr— >length = strlen (strptr) ; 
/* put node into the tree */ 
(void) tsearch ( (char *) nodeptr, Sroot, 

node_compare) ; 
/* adjust pointers, so we 

don't overwrite tree */ 
strptr += nodeptr->length + 1; 
nodeptr++; 
} 

twalk (root, print_node); 
} 
/* 

This routine compares two nodes, based on an 
alphabetical ordering of the string field. 
*/ 
int 

node_compare (nodel, node2) 
struct node *nodel, *node2; 
{ 

return strcmp(nodel->string, node2->string) ; 
} 
/* 

This routine prints out a node, the 
first time twalk. encounters it. 
*/ 
void 
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print_node (node, order, level) 

struct node **node; 

VISIT order; 

int level; 

{ 

if (order == preorder | | order == leaf) { 

(void) printf ("string = %20s, length = %d\n", 
(*node)->string, (*node)— >length) ; 

} 
} 

RETURN VALUE 

A NULL pointer is returned by tsearch if there is not 
enough space available to create a new node. 

A NULL pointer is returned by tsearch, tfind and 
tdelete if rootp is NULL on entry. 

If the datum is found, both tsearch and tfind return a 
pointer to it. If not, tfind returns NULL, and tsearch re- 
turns a pointer to the inserted item. 

SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

WARNINGS 

The root argument to twalk is one level of indirection less 
than the rootp arguments to tsearch and tdelete. 
There are two nomenclatures used to refer to the order in 
which tree nodes are visited, tsearch uses preorder, postord- 
er and endorder to respectively refer to visting a node before 
any of its children, after its left child and before its right, and 
after both its children. The alternate nomenclature uses preord- 
er, inorder and postorder to refer to the same visits, which 
could result in some confusion over the meaning of postorder. 

BUGS 

If the calling function alters the pointer to the root, results are 
unpredictable. 
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NAME 

t tyname, i s at ty — find name of a terminal 

SYNOPSIS 

char *ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 

DESCRIPTION 

t tyname returns a pointer to a string containing the null- 
terminated pathname of the terminal device associated with file 
descriptor fildes. 

RETURN VALUE 

t tyname returns a NULL pointer if fildes does not describe a ter- 
minal device in directory /dev. 

isatty returns 1 if fildes is associated with a terminal device; 
otherwise, it returns 0. 

FILES 

/dev/* 

BUGS 

The return value points to static data whose content is overwritten 
by each call. 
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NAME 

ttyslot — find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot () 

DESCRIPTION 

ttyslot returns the index of the current user's entry in the 
/etc /utmp file. This is accomplished by scanning the file 
/etc/inittab for the name of the terminal device associated 
with the standard input, the standard output, or the error output (0, 
1, or 2). 

SEE ALSO 

getut(3C), ttyname(3C). 

FILES 

/etc/inittab 
/etc /utmp 

RETURN VALUE 

A value of is returned if an error is encountered while searching 
for the terminal name or if none of the above file descriptors is as- 
sociated with a terminal device. 
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NAME 

umount — unmount a file system 

SYNOPSIS 

int umount (spec) 
char *spec; 

DESCRIPTION 

umount requests that a previously mounted file system contained 
on the block special device identified by spec be unmounted, spec 
is a pointer to a path name. After unmounting the file system, the 
directory upon which the file system was mounted reverts to its or- 
dinary interpretation. 

umount may be invoked only by the superuser. 

ERRORS 

umount will fail if one or more of the following are true: 

[eperm] The process's effective user ID is not su- 

peruser. 

[ ENXI ] spec does not exist. 

[ enotblk ] spec is not a block special device. 

[ E INVAL ] spec is not mounted. 

[ EBUS Y ] A file on spec is busy. 

[ efault ] spec points to an illegal address. 

RETURN VALUE 

Upon successful completion a value of is returned. Otherwise, a 
value of -1 is returned and errno is set to indicate the error. 

SEE ALSO 

f smount(2), unmount(2), mount(3). 
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NAME 

ungetc — push character back into input stream 

SYNOPSIS 

♦include <stdio.h> 

int ungetc (c, stream) 
char c; 
FILE * stream; 

DESCRIPTION 

ungetc inserts the character c into the buffer associated with an 
input stream. That character, c, will be returned by the next getc 
call on that stream, ungetc returns c and leaves the file stream 
unchanged. 

One character of pushback is guaranteed provided something has 
been read from the stream and the stream is actually buffered. In 
the case that stream is stdin, one character may be pushed back 
onto the buffer without a previous read statement. 

If c equals EOF, ungetc does nothing to the buffer and returns 
EOF. 

f seek(3S) erases all memory of inserted characters. 

RETURN VALUE 

ungetc returns EOF if it can't insert the character. 

SEE ALSO 

fseek(3S), getc(3S), setbuf(3S). 
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NAME 

varargs — handle variable argument list 

SYNOPSIS 

♦include <varargs.h> 

va_alist 

va_dcl 

void va_start (pvar) 
va_list pvar; 

type va_arg (pvar, type) 
va_list pvar; 

void va_end(pvar) 
va_list pvar; 

DESCRIPTION 

This set of macros allows portable procedures that accept variable 
argument lists to be written. Routines that have variable argument 
lists (such as print f(3S)) but do not use varargs are inherent- 
ly nonportable, as different machines use different argument- 
passing conventions. 

va_alist is used as the parameter list in a function header. 

va_dcl is a declaration for va_alist. No semicolon should 
follow va_dcl. 

va_list is a type defined for the variable used to traverse the 
list 

va_start is called to initialize pvar to the beginning of the list 

va_arg will return the next argument in the list referenced by 
pvar. type is the type the argument is expected to be. Different 
types can be mixed, but it is up to the routine to know what type of 
argument is expected, as it cannot be determined at runtime. 

va_end is used to clean up. 

Multiple traversals, each bracketed by va_start ... va_end, 
are possible. 

EXAMPLES 

This example is a possible implementation of exec 1(2). 

#include <varargs.h> 
#define MAXARGS 100 
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/*execl is called by 

execl{file, argl, arg2, ..., (char *)0); 
*/ 

execl (va_alist) 
va_dcl 
{ 

va_list ap; 
char *file; 
char *args[MAXARGS]; 
int argno = 0; 

va_start (ap) ; 

file = va_arg(ap, char *); 

while ( (args[argno++] = va_arg(ap, char *)) != (char *)0) 

va_end(ap) ; 

return execv(file, args) ; 
} 

SEE ALSO 

exec(2), print f(3S). 

BUGS 

It is up to the calling routine to specify how many arguments there 
are, since it is not always possible to determine this from the stack 
frame. For example, execl is passed a zero pointer to signal the 
end of the list print f can tell how many arguments are there 
by the format 

It is non-portable to specify a second argument of char, short, 
or float to va_arg, since arguments seen by the called func- 
tion are not char, short, or float. C converts char and 
short arguments to int and converts float arguments to 
double before passing them to a function. 
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NAME 

vprintf , vfprintf, vsprintf — format and output data 
from a variable-length argument list 

SYNOPSIS 

#include <stdio.h> 
finclude <varargs.h> 

int vprintf {format, ap) 
char * format; 
va_list ap; 

int vfprintf {stream , format, ap) 
FILE * stream; 
char * format; 
va_list ap; 

int vsprintf (s, format, ap) 
char *s, *format; 
va_list ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as 
print f, fprintf , and sprint f respectively, except that in- 
stead of being called with a variable number of arguments, they 
are called with an argument list as defined by varargs(5). 

EXAMPLES 

The following demonstrates how vfprintf could be used to 
write an error routine. 

#include <stdio.h> 
#include <varargs.h> 



/* 

* error should be called like 

* error (function_name, format, argl, arg2...); 
*/ 

/*VARARGS0*/ 

void 

error (va_alist) 

/* Note that the function_name and format arguments 

* cannot be separately declared because of the 
*/definition of varargs. 

va_dcl 
{ 

va_list args; 

char *fmt; 
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va_start (args) ; 

/* print out name of function causing error */ 

(void)fprintf (stderr, "ERROR in %s: ", 

va_arg(args f char *)); 
fmt = va_arg(args, char *); 
/* print out remainder of message */ 
(void) vfprintf (fmt, args); 
va_end (args) ; 
(void) abort ( ) ; 



} 



SEE ALSO 

varargs(5). 
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NAME 

xdr — library routines for external data representation 

DESCRIPTION 

These routines allow C programmers to describe arbitrary data 
structures in a machine-independent fashion. Data for remote pro- 
cedure calls are transmitted using these routines. 

FUNCTIONS 



xdr_array () 

xdr_bool ( ) 

xdr_bytes () 

xdr_destroy ( ) 

xdr_double ( ) 

xdr_enum ( ) 

xdr_float () 

xdr_getpos ( ) 

xdr_inline ( ) 

xdr_int ( ) 

xdr_long() 

xdr_opaque ( ) 

xdr_ref erence ( ) 
xdr_setpos ( ) 

xdr_short () 

xdr_string() 

xdr u int ( ) 



translate arrays to/from external 
representation 

translate Booleans to/from exter- 
nal representation 
translate counted byte strings 
to/from external representation 
destroy XDR stream and free as- 
sociated memory 
translate double precision to/from 
external representation 
translate enumerations to/from 
external representation 
translate floating point to/from 
external representation 
return current position in XDR 
stream 

invoke the in-line routines associ- 
ated with XDR stream 
translate integers to/from external 
representation 

translate long integers to/from 
external representation 
translate fixed-size opaque data 
to/from external representation 
chase pointers within structures 
change current position in XDR 
stream 

translate short integers to/from 
external representation 
translate null-terminated strings 
to/from external representation 
translate unsigned integers 
to/from external representation 
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xdr_u_long ( ) 



translate unsigned long integers 
to/from external representation 
translate unsigned short integers 
to/from external representation 
translate discriminated unions 
to/from external representation 
always return one (1) 
package RPC routine for XDR 
routine, or vice-versa 
initialize an XDR stream 
initialize an XDR stream with 
record boundaries 
xdrrec_endof record ( ) mark XDR record stream with an 

end-of-record 

mark XDR record stream with an 
end-of-file 



xdr_u_short ( ) 

xdr_union() 

xdr__void ( ) 
xdr_wrapstring () 

xdrmem_create () 
xdrrec create () 



xdrrec eof () 



xdrrec skiprecordO 



xdrstdio create () 



skip remaining record in XDR 
record stream 

initialize an XDR stream as stan- 
dard I/O FILE stream 



SEE ALSO 

AIUX Network Applications Programming. 
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NAME 

yp_bind, yp_unbind, yp_get_default_domain, 
yp_match, yp_first, yp_next, yp_all, yp_order, 
yp_master, yperr_string, ypprot_err — yellow 
pages client interface 

SYNOPSIS 

♦include <rpcsvc/ypclnt . h> 

yp_bind (indomain) ; 
char *indomain; 

void yp_unbi nd ( indomain ) 
char *indomain; 

yp_get_def ault_domain (outdomain) ; 
char ** outdomain; 

yp_match (indomain, inmap, inkey, inkeylen, outval, 

outvallen) 

char * indomain; 

char * inmap; 

char * inkey; 

int inkeylen; 

char ** outval; 

int * outvallen; 

yp_f irst (indomain , inmap, outkey, outkeylen, outval, 

outvallen) 

char *indomain; 

char *inmap; 

char **outkey; 

int * outkeylen; 

char ** outval; 

int * outvallen; 

yp_next (indomain, inmap, inkey, inkeylen, outkey, 

outkeylen, outval, outvallen) ; 

char * indomain; 

char *inmap; 

char * inkey; 

int inkeylen; 

char ** outkey; 

int * outkeylen; 

char **outval; 

int * outvallen; 
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yp_all (indomain, inmap, incallback) ; 

char * indomain; 

char * inmap; 

struct ypall_callback incallback; 

yp_order (indomain, inmap, outorder) ; 
char * indomain; 
char *inmap; 
int *outorder; 

yp_master (indomain, inmap, outname) ; 
char * indomain; 
char *inmap; 
char ** outname; 

char *yperr_string (incode) 
int incode; 

ypprot_err (incode) 
unsigned int incode; 

DESCRIPTION 

This package of functions provides an interface to the yellow 
pages (YP) network lookup service. The package can be loaded 
from the standard library /lib/libc . a. Refer to ypf iles(4) 
and ypserv(lM) for an overview of the yellow pages, including 
the definitions of map and domain, and a description of the vari- 
ous servers, databases, and commands that comprise the YP. 

All input parameters names begin with "in". Output parameters 
begin with "out". Output parameters of type "char **" 
should be addresses of uninitialized character pointers. Memory 
is allocated by the YP client package using malloc(3), and may 
be freed if the user code has no continuing need for it. For each 
outkey and outval, two extra bytes of memory are allocated at the 
end that contain NEWLINE and NULL, respectively, but these 
two bytes are not reflected in outkeylen or outvallen. 

indomain and inmap strings must be non-null and null-terminated. 
String parameters which are accompanied by a count parameter 
may not be null, but may point to null strings, with the count 
parameter indicating this. Counted strings need not be null- 
terminated. 

All functions in this package of type "int" return if they 
succeed, and a failure code (yperrjoxc) otherwise. Failure 
codes are described under ERRORS below. 
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The YP lookup calls require a map name and a domain name, at 
minimum. It is assumed that the client process knows the name of 
the map of interest. Client processes should fetch the node's de- 
fault domain by calling yp_get_default_domain() , and 
use the returned outdomain as the indomain parameter to succes- 
sive YP calls. 

To use the YP services, the client process must be "bound" to a 
YP server that serves the appropriate domain using yp_bind. 
Binding need not be done explicitly by user code; this is done au- 
tomatically whenever a YP lookup function is called. yp_bind 
can be called directly for processes that make use of a backup 
strategy (e.g., a local file) in cases when YP services are not avail- 
able. 

Each binding allocates (uses up) one client process socket descrip- 
tor; each bound domain costs one socket descriptor. However, 
multiple requests to the same domain use that same descriptor. 
yp_unbind ( ) is available at the client interface for processes 
that explicitly manage their socket descriptors while accessing 
multiple domains. The call to yp_unbind ( ) make the domain 
"unbound," and free all per-process and per-node resources used 
to bind it. 

If an RPC failure results upon use of a binding, that domain will 
be unbound automatically. At that point, the ypclnt layer will 
retry forever or until the operation succeeds, provided that yp- 
bind is running, and either 

the client process can't bind a server for the proper domain, 
or 

RPC requests to the server fail. 

If an error is not RPC-related, or if ypbind is not running, or if a 
bound ypserv process returns any answer (success or failure), 
the ypclnt layer will return control to the user code, either with 
an error code, or a success code and any results. 

yp_match returns the value associated with a passed key. This 
key must be exact; no pattern matching is available. 

yp_f irst returns the first key- value pair from the named map in 
the named domain. 
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yp_next ( ) returns the next key-value pair in a named map. 
The inkey parameter should be the outkey returned from an initial 
call to yp_f i r s t ( ) (to get the second key- value pair) or the one 
returned from the nth call to yp_next ( ) (to get the nth + second 
key-value pair). 

The concept of first (and, for that matter, of next) is particular to 
the structure of the YP map being processing; there is no relation 
in retrieval order to either the lexical order within any original 
(non-YP) data base, or to any obvious numerical sorting order on 
the keys, values, or key-value pairs. The only ordering guarantee 
made is that if the yp_f irst ( ) function is called on a particular 
map, and then the yp_next ( ) function is repeatedly called on 
the same map at the same server until the call fails with a reason 
of YPERR_NOMORE, every entry in the data base will be seen ex- 
actly once. Further, if the same sequence of operations is per- 
formed on the same map at the same server, the entries will be 
seen in the same order. 

Under conditions of heavy server load or server failure, it is possi- 
ble for the domain to become unbound, then bound once again 
(perhaps to a different server) while a client is running. This can 
cause a break in one of the enumeration rules; specific entries may 
be seen twice by the client, or not at all. This approach protects 
the client from error messages that would otherwise be returned in 
the midst of the enumeration. The next paragraph describes a 
better solution to enumerating all entries in a map. 

yp_all provides a way to transfer an entire map from server to 
client in a single request using TCP (rather than UDP as with oth- 
er functions in this package). The entire transaction take place as 
a single RPC request and response. You can use yp_all just 
like any other YP procedure, identify the map in the normal 
manner, and supply the name of a function which will be called to 
process each key-value pair within the map. You return from the 
call to yp_all only when the transaction is completed (success- 
fully or unsuccessfully), or your "foreach" function decides 
that it doesn't want to see any more key-value pairs. 

The third parameter to yp_all is 

struct ypall_callback *incallback { 
int (*foreach) () ; 
char *data; 
}; 
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The function fo reach is called 

fo reach (instatus, inkey, inkeylen, inval, invallen, indata) ; 

int instatus; 

char *inkey; 

int inkeylen; 

char * inval; 

int invallen; 

char *indata; 

The instatus parameter will hold one of the return status values 
defined in <rpcsvc/yp_prot . h>; either YP_TRUE or an error 
code. (See ypprot_err, below, for a function which converts a 
YP protocol error code to a ypclnt layer error code.) 

The key and value parameters are somewhat different than defined 
in the synopsis section above. First, the memory pointed to by the 
inkey and inval parameters is private to the yp_all function, and 
is overwritten with the arrival of each new key- value pair. It is the 
responsibility of the f oreach function to do something useful 
with the contents of that memory, but it does not own the memory 
itself. Key and value objects presented to the f oreach function 
look exactly as they do in the server's map; if they were not 
newline- terminated or null-terminated in the map, they won't be 
here either. 

The indata parameter is the contents of the incallback->data ele- 
ment passed to yp_all. The data element of the callback struc- 
ture may be used to share state information between the 
f oreach function and the mainline code. Its use is optional, and 
no part of the YP client package inspects its contents; cast it to 
something useful, or ignore it as you see fit. 

The f oreach function is a Boolean. It should return zero to in- 
dicate that it wants to be called again for further received key- 
value pairs, or non-zero to stop the flow of key-value pairs. If 
foreach returns a non-zero value, it is not called again; the 
functional value of yp_all is then 0. 

yp_order returns the order number for a map. 

yp_master returns the machine name of the master YP server 
for a map. 
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yperr_string returns a pointer to an error message string that 
is null-terminated but contains no period or newline. 

ypprot_err takes a YP protocol error code as input, and re- 
turns a ypclnt layer error code, which may be used in turn as an 
input to yperr_string. 

ERRORS 

All integer functions return if the requested operation is success- 
ful, or one of the following errors if the operation fails. 

/* args to function are bad */ 
/* RPC failure - domain has 

been unbound */ 
/* can't bind to server on this 

domain */ 
/* no such map in server's 

domain */ 
/* no such key in map */ 
/* internal yp server or 

client error */ 
/* resource allocation 

failure */ 
/* no more records in map 

database */ 
/* can't communicate with 

portmapper */ 
/* can't communicate with 

ypbind */ 
/* can't communicate with 

ypserv */ 
_ /* local domain name not set */ 

FILES 

/usr/include/rpcsvc/ypclnt . h 
/usr/include/rpcsvc/yp_prot . h 

SEE ALSO 

ypserv(lM), ypf iles(4). 



♦define 


YPERR 


BADARGS 


1 


tdefine 


yperr" 


RPC 


2 


#define 


YPERR_ 


_DOMAIN 


3 


tdefine 


YPERR_ 


_MAP 


4 


tdefine 


YPERR 


KEY 


5 


tdefine 


yperr] 


_YPERR 
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tdefine 


YPERR_ 


_RESRC 
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tdefine 


YPERR_ 


_NOMORE 
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tdefine 


YPERR_ 


_PMAP 
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tdefine 


YPERR_ 


_YPBIND 


10 


tdefine 


YPERR_ 


YPSERV 


11 


tdefine 


YPERR 


NODOM 


12 
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NAME 

yppasswd — update user password in yellow pages 

SYNOPSIS 

#include <rpcsvc/yppasswd.h> 

yppas svid{oldpass r newpw) 

char *oldpass; 

struct passwd *newpw; 

DESCRIPTION 

If oldpass is indeed the old user password, this routine replaces 
the password entry with newpw. It returns if successful. 

RPC INFO 

Program number: yppas swdprog 

xdr routines: 

xdr_ppasswd(;a/r.y, yp) 

XDR *xdrs; 

struct yppasswd *yp; 
xdr_yppasswd (xdrs, pw) 

XDR *xdrs; 

struct passwd *pw; 

Procs: 

YPPAS SWDPROCJJPDATE 

Takes the structure yppasswd as an argument; returns in- 
teger. Same behavior as the yppasswd () wrapper. Uses 
UNIX authentication. 

Versions: 

YPPASSWDVERS_ORIG 

Structures: 

struct yppasswd { 

char *oldpass; /* old (unencrypted) pw */ 
struct passwd newpw; /* new pw structure */ 

}; 

SEE ALSO 

yppasswd(l), yppas swdd(lM). 
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NAME 

zip_getmyzone, zip_getzonelist, 
zip_getlocalzones — AppleTalk Zone Information 
Protocol (ZIP) interface 

SYNOPSIS 

♦include <at/appletalk.h> 
♦include <at/zip.h> 
cc {flags] files -lat [libraries] 

int zip_getmyzone (zone) at_nvestr_t *zone; 

int zip_getzonelist (start, zones) int start; 
at_nvestr_t * zones [] ; 

int zip_get local zones (start, zones) int start; 
at_nvestr_t * zones [] ; 

DESCRIPTION 

The ZIP interface provides applications with access to the Ap- 
pleTalk Zone Information Protocol operations. 

The zip_getmyzone routine obtains the zone name for the lo- 
cal network. In the case of LocalTalk, this involves sending a ZIP 
request to a local bridge to get the zone name of the default net- 
work. In the case of EtherTalk, the request is completed on the 
node itself. The parameters are 

zone A pointer to the zone name. The zone string is defined 
by the following structure (see <at /nbp . h>) : 





typedef struct at_nvestr { 




u_char len; 




u_cha r s t r [ NBP_NVE_STR_S I ZE ] ; 




} at_nves t r_t ; 


len 


The size of the string in bytes. 


str 


The zone name. 



This routine returns upon success. 

The zip_getzonelist routine obtains a complete list of all 
the zone names defined in the internet. This routine sends a ZIP 
request to a bridge for the list of zone names in the internet The 
list is placed in the supplied buffer as concatenated 
at_nvestr_t structures. The parameters are 
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start The starting index for the get zone list request. The start 
index is the value of the index at which to start including 
zone names in the response. It is used to obtain a zone 
list that may not fit into one ATP response packet The 
start index should initially be 1. While 
zip_getzonelist returns a value greater than 0, the 
caller must reissue zip_getzonelist calls to get 
more zone names from the bridge, specifying a start in- 
dex of the previous start index plus the previous return 
value of zip_getzonelist. 

buf A buffer to hold this list of zone names. Each zone 
name is an at_nvestr_t structure. The size of this 
buffer (in bytes) must be at least atp_data_si ze. 

Upon successful completion, this routine returns the number of 
zone names in the list 

When all zones in the bridge's Zone Information Table have been 
returned, this routine returns 0. 

The use and behavior of the zip_getlocal zones routine are 
the same as for zip_getzonelist, except that the former re- 
turns the list of zones on the local EtherTalk cable rather than all 
the zones on the internet. On LocalTalk, 
zip_get local zones returns only the current zone name. 

DIAGNOSTICS 

All routines return -1 on error, with a detailed error code stored in 

errno: 

[ E I nval ] A parameter is invalid. 

[ enetunreach ] A bridge node could not be found to pro- 
cess the request. 

Routines also return any error codes returned by the underlying 
ATP or DDP layers. 

SEE ALSO 

ddp(3N), atp(3N), Inside AppleTalk; "AppleTalk Programming 
Guide," in AiUX Network Applications Programming. 

WARNINGS 

The returned zone strings are not NULL-terminated. 
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NAME 

intro — introduction to file formats 

DESCRIPTION 

This section outlines the formats of various files. The C struct 
declarations for the file formats are given where applicable. Usu- 
ally, these structures can be found in the directories 
/usr/include or /usr/include/sys. 
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NAME 

a . out — common assembler and link editor output 

DESCRIPTION 

a . out is the output file from the assembler as(l) and the link ed- 
itor ld(l). a . out can be executed on the target machine if there 
were no errors in assembling or linking and no unresolved exter- 
nal references. 

The object file format supports user-defined sections and contains 
extensive information for symbolic software testing. A common 
object file consists of a file header, an optional a out header, a 
table of section headers, relocation information, (optional) line 
numbers, and a symbol table. The order is given below. 

File header. 

Optional a out header. 

Section 1 header. 

Section n header. 
Section 1 data. 

Section n data. 
Section 1 relocation. 

Section n relocation. 
Section 1 line numbers. 

Section n line numbers. 
Symbol table. 
String table. 

The last four sections (relocation, line numbers, symbol table, and 
string table) may be missing if the program was linked with the -s 
option of ld(l) or if the symbol table and relocation bits were re- 
moved by strip(l). Also note that if the program was linked 
without the -r option, the relocation information will be absent 
The string table exists only if necessary. 

When an a . out file is loaded into memory for execution, three 
logical segments are set up: the text segment, the data segment 
(initialized data followed by uninitialized data, the latter actually 
being initialized to all O's), and a stack. The text segment begins 
at location in the core image; the header is not loaded. If the 
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magic number (the first field in the optional a out header) is 407 
(octal), it indicates that the text segment is not to be write- 
protected or shared, so the data segment will be contiguous with 
the text segment. If the magic number is 410 (octal), the data seg- 
ment begins at the next segment boundary following the text seg- 
ment, and the text segment is not writable by the program. If oth- 
er processes are executing the same a . out file, they will share a 
single text segment 

On the Macintosh II with A/UX the stack begins at the end of 
memory and grows toward lower addresses. The stack is automat- 
ically extended as required. The data segment is extended only as 
requested by the brk(2) and sbrk(2) system calls. 

The value of a word in the text or data portions that is not a refer- 
ence to an undefined external symbol is exactly the value that will 
appear in memory when the file is executed. If a word in the text 
involves a reference to an undefined external symbol, the storage 
class of the symbol-table entry for that word will be marked as an 
"external symbol", and the section number will be set to 0. 
When the file is processed by the link editor and the external sym- 
bol becomes defined, the value of the symbol will be added to the 
word in the file. 

See aouthdr(4), f ilehdr(4), linenum(4), scnhdr(4), re- 
loc(4), and syms(4) for descriptions of the individuals parts. 
Every section created by as(l) contains a multiple-of-four 
number of bytes; directives to ld(l) can create a section with an 
odd number of bytes. 

SEE ALSO 

as(l), cc(l), ld(l), ldfcn(3X), aouthdr(4), 
filehdr(4), linenum(4), reloc(4), scnhdr(4), 
syms(4). 
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NAME 

acct 



per-process accounting file format 



SYNOPSIS 

♦include <sys/acct.h> 

DESCRIPTION 

Files produced as a result of calling acct(2) have records in the 
form defined by <sys/acct . h>, whose contents are 



typedef ushort comp_t; 



struct 
char 
char 
ushort 
ushort 
dev_t 
time_t 
comp t 



acct { 
ac_f lag; 
ac_stat; 
ac_uid; 
ac_gid; 
ac_tty; 
ac_btime; 
ac utime; 



floating point */ 
13-bit fraction, 3-bit 
exponent */ 



"/ 



/* Accounting flag 

/* Exit status */ 

/* Accounting user ID */ 

/* Accounting group ID */ 

/* control terminal */ 

/* Beginning time */ 

/* acctng user time in 
clock ticks */ 

/* acctng system time in 
clock ticks */ 

/* acctng elapsed time in 
clock ticks */ 
ac_mem; /* memory usage in clicks */ 
ac_io; /* chars trnsfrd by read/write */ 
ac_rw; /* number of block reads/writes */ 
ac comm[8]; /* command name */ 



comp_t ac stime; 



comp t ac etime; 



comp_t 
comp_t 
comp_t 

char 



extern 

extern 



struct acct acctbuf; 

struct vnode *acctp; /* vnode of acctng file */ 



#define AFORK 
#define ASU 
#define ACCTF 



01 


/ 


02 


/ 


0300 


/ 



has executed fork-no exec */ 
used superuser privileges */ 
record type: 00 = acct */ 



In ac_f lag, the AFORK flag is turned on by each f ork(2) and 
turned off by an exec(2). The ac_comm field is inherited from 
the parent process and is reset by any exec. Each time the sys- 
tem charges the process with a clock tick, it also adds the current 
process size to ac_mem, computed as follows: 

(data size) + (text size) / (number of in-core processes using text) 

The value of ac_mem/ (ac_stime+ac_utime) can be 
viewed as an approximation to the mean process size, as modified 
by text-sharing. 
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The structure tacct, which resides with the source files of the 
accounting commands, represents the total accounting format used 
by the various accounting commands. 

/* 

/* total accounting (for acct period) , also for day 
/* 



struct tacct { 
uid_t 
char 
float 

float 

float 



ta_ 


uid; 


ta" 


name [8] ; 


ta~ 


_cpu[2]; 


ta_ 


_kcore[2] 


ta_ 


_con[2]; 


ta_ 


_du; 


ta] 


_pc; 



float 

long 

unsigned short ta_sc; 

unsigned short tadc; 

unsigned short ta fee; 



/* userid */ 
/* login name */ 
/* cum. cpu time, 
p/np (mins) */ 
/* cum kcore-minutes, 

p/np */ 
/* cum. connect time, 

p/np, mins */ 
/* cum. disk usage */ 
/* count of processes */ 
/* count of login 

sessions */ 
/* count of disk 

samples */ 
/* fee for special 

services */ 



}; 



SEE ALSO 

acct(lM), acctcom(lM), acct(2), exec(2), f ork(2). 

BUGS 

The ac_mem value for a short-lived command gives little infor- 
mation about the actual size of the command, because ac__mem 
may be incremented while a different command (for example, the 
shell) is being executed by the process. 
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NAME 

af m — Adobe PostScript font metrics file format 

DESCRIPTION 

afm files are a standard interchange format for communicating 
PostScript font metric information to people and programs. The 
format is ASCII encoded (for both human and machine readabili- 
ty), machine independent, extensible, simple to parse, and simple 
to generate, afm files are available for all of Adobe Systems' 
PostScript fonts. 

While somewhat verbose, the format is intended to be easily 
parsed, with the ability for applications to quickly skip over items 
that are not of interest It should be possible to create simple 
line-oriented parsing programs, or tools based on awk(l) or 
sed(l). 

Each afm file contains the information for only one font face. 
The file begins with global information about the font, followed 
by sections with character metrics. The file format is line- 
oriented, each line beginning with a property (key) name, fol- 
lowed by the values for that property. The general idea is to give 
key-value tuples (much like in a PostScript font dictionary). 

The format is: 

key [value value . . .] 

Key names are case-sensitive. All keys beginning with a capital 
letter are reserved by Adobe Systems. The standard keys are de- 
tailed below, but other keys should be allowed and safely ignored 
by programs not recognizing them. All standard keys begin with a 
capital letter. User-defined nonstandard entries should begin with 
a lowercase letter. 

The file begins with the line: 

StartFontMetri.es version 

The version described here is 1.0. The last line of the file is: 

EndFontMetrics 

The following global font keys are defined. Many of them are 
defined as in the top level or Fontlnfo subdictionary of a 
PostScript font dictionary; their meanings are described in Ap- 
pendix A of the PostScript Language Manual. All numeric 
values are in the (1000 unit per em) character coordinate system. 
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The name of the font as presented 
to the PostScript findfont 
operator. 

The "print name" of the font. 

The font family name. 

The weight of the font. 

The angle (in degrees counter 
clockwise from the vertical) of the 
dominant staffs of the font 

Indicates monospaced (typewriter) 
fonts. 

Four integers giving the lower left 
corner and the upper right corner 
of the font bounding box. 

Note: The bounding box 
given here is that of the 
flattened paths, not of the 
Bezier curve descriptions. 

UnderlinePosition number 

The position (from the baseline) to 
place an underline. 

UnderlineThickness number 

Thickness of an underline stroke. 



FontName string 

FullName string 
FamilyName string 
Weight string 
ItalicAngle real 

IsFixedPitch boolean 
FontBBox llx lly urx wry 



Version string 
Notice string 

Comment string 
EncodingScheme string 



CapHeight number 



Font version identifier. 

Font name trademark or copyright 
notice. 

Comment strings may be ignored. 

a string indicating the default en- 
coding vector for this font The 
most common one is Adobe S- 
tandardEncoding. Special 
fonts may simply state 
FontSpecific. In the future, 
other schemes may be employed. 

Top of capital H. 
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XHeight number 
Ascender number 



Top of lowercase x. 
Top of lowercase d. 



De s cende r number Bottom of lowercase p. 

The individual character metrics are surrounded with the lines 
StartCharMetrics and EndCharMetrics and consist of a 
list of keys and values separated by semicolons. The characters 
are sorted (numeric ascending) by character code. Unencoded 
characters follow all of the encoded ones and are distinguished by 
having character code -1. Each character gets one line of descrip- 
tion. Standard keys are: 



C number 

wx width-x 

w width-x width-y 

N name 

B llx lly urx ury 

L successor ligature 



decimal value of default PostScript 
character code (-1 if unencoded). 

Character width in x (y is 0). 

Character width vector. 

PostScript character name. 

The character bounding box. 

A ligature sequence. The current char- 
acter may join with the character 
named successor to form the character 
named ligature. Note that characters 
may have more than one such entry. 

Most western language fonts have wx entries rather than w ones. 
Note that keys are one letter for brevity. Here too, the set is exten- 
sible, with unknown entries ignored. (This leaves room for addi- 
tion of new information, for example.) A future revision of this 
format will have a specification for kerning information. 

FILES 

/usr/lib/ps/* . afm AFM files in the TRANSCRIPT distribu- 
tion. 

SEE ALSO 

awk(l), sed(l). 
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NAME 

aliases — aliases file for sendmail 

SYNOPSIS 

/usr /lib/aliases 

DESCRIPTION 

This file describes user ID aliases that /etc /sendmail uses. It 
is a series of lines of the form 

name-.addrl ,addr2, . . .addrn 

The name is the name to alias, and the addr's are the addresses to 
send the message to. Lines beginning with white space are con- 
tinuation lines. Lines beginning with # are comments. 

Aliasing occurs only on local names. Loops cannot occur, since 
no message is sent to any person more than once. 

FILES 

/usr/ lib/ aliases 

SEE ALSO 

sendmail(lM). 
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NAME 

altblk — alternate block information for bad block handling 

SYNOPSIS 

tinclude <sys/types.h> 
♦include <apple/abm.h> 

DESCRIPTION 

abm is the data structure used by A/UX disk device drivers to han- 
dle bad blocks for disk partitions that support alternate block bad 
block handling. The abm structure can be retrieved through an 
ioctl(2) with a request of GD_GETABM. The actual contents of 
the alternate block map can be retrieved via the abmi structure 
through an ioctl(2) with a request of GD_GETMAP. The abmi 
structure is described in gd(7). The format of the abm structure 
is: 

struct abm /* altblk map info stored in bzb */ 

{ 

int abm_size; /* size of map (bytes) */ 
int abm_ents; /* number of used entries 

(bytes) */ 
daddr_t abm_start; /* start of altblk map 

(phys blk num) */ 
}; 

typedef struct abm ABM; 

#define ABM_ENTSIZ (sizeof (long) ) /* size of each 

map entry */ 

tdefine NO_ALTMAP ( (daddr_t) 0) /* value of abm_off 

field if no map */ 

#define ABM_FREE -1 /* block not used */ 

#define ABM_BADBLK -2 /* block is bad */ 

tdefine ABM_ABM -3 /* part of AltBlkMap */ 

#define ABM_MAXVAL -16 /* last reserved map value */ 

Normally the alternate block area, that area between the end of the 
logical partition and the end of the physical partition, will (option- 
ally) contain an alternate block map and alternate block data 
blocks for alternate block handling. The alternate block map re- 
sides anywhere in the alternate block area, in a contiguous set of 
blocks. The format of the alternate block map is an array of long 
integers. Each indexed location in the array corresponds to a po- 
tential alternate block in the alternate block area. A location in the 
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alternate block array (map) may either contain the number of a 
block in the logical partition of the disk partition which will be 
remapped, or it may contain a flag. 

The currently recognized flag values are abm_free for available 
blocks, abm_badblk if the free block is bad, and abm_abm to 
indicate that the block is allocated to the alternate block map. 
Flag values with in the range of abm_abm and abm_maxval are 
reserved for future use. 

Alternate block mapping may be disabled through an ioctl(2) 
with the request GD_altblk. A bad block may be alternate 
blocked through an ioctl(2) with the request GDMKBAD. 

HELD DESCRIPTIONS 

abm_size 

This field contains the size of the alternate block map as 
measured in bytes. This value should always be evenly 
divisible by ABM_ENTS I z. The value of this field should be 
consulted when requesting the contents of the alternate block 
map through an ioctl(2). 

abm_ents 

The value of this field represents the byte offset of the next 
available entry in the alternate block map as measured from 
the beginning of the map. This field is maintained by the 
device driver. 

abm_start 

The value of this field is set to no_altmap to indicate that 
there is no alternate block map for the corresponding parti- 
tion. If the value of this field is not set to no_altmap, then 
the value is the physical block number (relative to the start of 
the physical partition) of the first block of the alternate block 
map. 

SEE ALSO 

badblk(lM), dp(lM), bzb(4), gd(7). 
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NAME 

aouthdr — a . out header for common object files 

SYNOPSIS 

#include <aouthdr.h> 

DESCRIPTION 

aouthdr is an optional a . out header for common object files. 
The C structure follows: 



/* 



* static char ID_aouth[] = "@ (#) aouthdr. h 2.1 
*/ 





short 


magic; 


/ 




short 


vstamp; 


/ 




long 


tsize; 


/ 




long 


dsize; 


/ 




long 


bsize; 


/ 


tifdef 


u3b 








long 


duml ; 






long 


dum2 ; 


/ 


#endif 










long 


entry; 


/ 




long 


text start, 


;/ 




long 


data start, 


;/ 


} AOUTHDR; 






SEE ALSO 








a . out(4). 







see magic. h */ 
version stamp */ 
text size in bytes, 
padded to FW bdry */ 
initialized data " " 
uninitialized data " 



/*Pad to entry point */ 

entry pt. */ 
base of text used 
for this file */ 
base of data used 
for this file */ 
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NAME 

appletalkrc — AppleTalk® network configuration file 

DESCRIPTION 

appletalkrc contains information for configuring an Ap- 
pleTalk network. The file is created at boot time by the AppleTalk 
startup routine and is configured for EtherTalk™ by default The 
format of the file consists of a list of parameters and values, one 
per line: 

parameter=value 

Comments are indicated by a # character and continue until the 
newline. The following parameters are defined: 

interface 

The name of the default AppleTalk interface. The 
value for this parameter can be either ethertalkO 
orlocaltalkO. 

ethernet 

The name of the hardware interface to be associated 
with the EtherTalk interface. The value for this 
parameter is a string such as aeO. 

EXAMPLES 

This is the default appletalkrc file created by the AppleTalk 
startup routine for a system with one EtherTalk card: 

# AppleTalk configuration file 
interface= ethertalkO 

ethernet= aeO 

FILES 

/etc/appletalkrc 
/etc/startup. d 
/etc/newunix 

SEE ALSO 

appletalk(lM), newunix(lM). 

"Installing and Administering AppleTalk," in A/UX Network Sys- 
tem Administration; Inside AppleTalk; "AppleTalk Programming 
Guide,' ' in A/UX Network Applications Programming. 
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NAME 

ar — common archive file format 

DESCRIPTION 

The archive command ar is used to combine several files into 
one. Archives are used mainly as libraries to be searched by the 
link editor ld(l). 

Each archive begins with the archive magic string 

#define ARMAG " ! <arch>\n" /* magic string */ 

#define SARMAG 8 /* length of magic string */ 

Each archive which contains common object files (see a . out (4)) 
includes an archive symbol table. This symbol table is used by the 
link editor ld(l) to determine which archive members must be 
loaded during the link-edit process. The archive symbol table (if 
it exists) is always the first file in the archive (but is never listed) 
and is automatically created or updated by ar. 

Following the archive magic string are the archive file members. 
Each file member is preceded by a file-member header which is of 
the following format 



tdefine 


ARFMAG 


ii 


«\n" /* 


header trailer string */ 


struct 
{ 


ar_hdr 




/* 


file 


member header */ 


char 


ar_ 


name [16]; 


■ /* 


'/' terminated file 












member name */ 




char 


ar 


date [12]; 


' /* 


file member date */ 




char 


ar 


_uid[6]; 


/* 


file member user 
identification */ 




char 


ar 


_gid[6]; 


/* 


file member group 
identification */ 




char 


ar 


mode [ 8 ] ; 


/* 


file member mode */ 




char 


ar 


_size[10]; 


' /* 


file member size */ 




char 


ar 


fmag[2] ; 


/* 


header trailer string 



}; 

All information in the file-member headers is in printable ASCII. 
The numeric information contained in the headers is stored as de- 
cimal numbers (except for ar_mode which is in octal). Thus, if 
the archive contains printable files, the archive itself is printable. 

The ar_name field is blank-padded and slash (J) terminated. The 
ar_date field is the modification date of the file at the time of its 
insertion into the archive. Common format archives can be moved 
from system to system as long as the portable archive command 
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ar(l)isused. 

Each archive file member begins on an even byte boundary; a 
newline is inserted between files if necessary. Nevertheless, the 
size given reflects the actual size of the file, exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a 
zero length name (that is, ar_name [ ] = ' / ' ). The contents 
of this file are as follows: 

• The number of symbols. Length: 4 bytes. 

• The array of offsets into the archive file. Length: 4 bytes 
times the number of symbols. 

• The name string table. Length: ar_size - (4 bytes times 
(the number of symbols+1)). The number of symbols and the 
array of offsets are managed with sgetl and sputl. The 
string table contains exactly as many null-terminated strings 
as there are elements in the offsets array. Each offset from 
the array is associated with the corresponding name from the 
string table (in order). The names in the string table are all 
the defined global symbols found in the common object files 
in the archive. Each offset corresponds to the location of the 
archive header for the associated symbol. 

SEE ALSO 

ar(l), ld(l), strip(l), sputl(3X), a . out(4). 

WARNINGS 

strip(l) will remove all archive symbol entries from the header. 
The archive symbol entries must be restored via the s option of 
the ar(l) command before the archive can be used with the link 
editor ld(l). 
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NAME 

bzb — format of Block Zero Blocks 

SYNOPSIS 

#include <sys/types.h> 
#include <apple/types.h> 
♦include <apple/bzb.h> 

DESCRIPTION 

The Block Zero Block structure occupies the first 
sizeof (struct bzb) bytes of the dpme_boot_args field 
of each A/UX disk partition map entry. This structure contains 
extra partition identification information that is of interest only to 
A/UX. The types of data stored in a Block Zero Block include file 
system identification and status information. The format of a 
Block Zero Block is 

/* block zero block format */ 

magic number */ 

autorecovery cluster 

grouping */ 

FS type */ 

bad block inode number */ 

FS is a root FS */ 

FS is a usr FS */ 

FS is a critical FS */ 

reserved for later use */ 

pad bitfield to 32 bits */ 

time of FS creation */ 

time of last mount */ 

time of last umount */ 

altblk map info */ 



#define BZBMAGIC ( (u32) OxABADBABE /* BZB magic number */ 
#define dpme bzb dpme_boot_args 



standard A/UX FS */ 
autorecovery FS */ 
swap FS */ 



struct 
{ 


bzb 






/ 


u32 




bzb magic; 


/ 




u8 




bzb cluster; 


/ 




u8 




bzb type; 


/ 




ul6 




bzb inode; 


/ 




ul6 




bzb root:l, 
bzb usr:l, 
bzb crit:l, 
bzb rsrvd:13; 


/ 
/ 
/ 
/ 




ul6 




bzb filler; 


/ 




time 


_t 


bzb tmade; 


/ 




time 


t 


bzb tmount; 


/ 




time_ 


t 


bzb tumount; 


/ 


}; 

typede 


ABM 




bzb abm; 


/ 


f struct 


bzb BZB; 





/* 










** File 


system 


types 






*/ 










tdefine 


FST 


((u8) 


Oxl) 


/ 


tdefine 


FSTEFS 


((u8) 


0x2) 


/ 


#define 


FSTSFS 


((u8) 


0x3) 


/ 
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HELD DESCRIPTIONS 

bzb_magic 

This field should always contain the magic number bzbmag- 
IC. If this field is not set to BZBMAGIC, the information in 
the Block Zero Block should be treated as invalid. 

bzb_cluster 

The value of this field determines the auto recovery (8) 
cluster to which the associated disk partition belongs. 

bzb_type 

This field identifies the type of A/UX file system correspond- 
ing to this Block Zero Block. Examples of A/UX file sys- 
tems are regular file systems, autorecovery file systems, 
and swap file systems (for these types, this field's values 
would be FST, FSTEFS, and FSTSFS, respectively). 

bzb_inode 

If nonzero, this field contains the number of the inode 
corresponding to the bad block file in the corresponding par- 
tition that will be used for bad blocking. If this field's value 
is zero, there is no bad block inode/file allocated. This file is 
made up of blocks that are bad (that is, blocks containing the 
contents of this file are all bad). This keeps the bad blocks 
out of the free list across f scks. This field is generally used 
only for file systems that reside on physical disks that lack 
hardware bad blocking or that support hardware bad blocking 
but have run out of spare bad blocks. This field is not sup- 
ported for swap file systems. 

The only supported values for this field are zero and one. 

bzb_root 

When on, this bit indicates that the file system located on the 
corresponding partition is a root file system. 

bzb_usr 

When on, this bit indicates that the file system located on the 
corresponding partition is a usr file system. If both this field 
and the bzb_root are on, the file system is a root/usr file 
system. 

bzb_crit 

When on, this bit indicates that the file system located on the 
corresponding partition is a critical file system. A critical file 
system receives special treatment during the Bad Block por- 
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tion of autorecovery. The swap file system is an exam- 
ple of a critical file system, and therefore, all swap file system 
Block Zero Blocks should have this field set 

If this bit is on, no attempt will be made to create or use a bad 
block file for bad block handling. 

bzb_rsrvd 

This field contains bits reserved for later use. 

bzb_filler 

This field is reserved for later use. 

bzb_tmade 

This field contains a time-stamp which indicates when the file 
system located on the corresponding partition was created. 
This field's value is the standard A/UX time-stamp value (as 
returned from time(2)). The value of this field can be set 
and retrieved through calls to ioctl(2). See gd(7) for more 
details. 

bzb_tmount 

This field indicates the date the last mount(3) (or equivalent 
routine) call was made on the file system located on the 
corresponding partition. In some cases, such as on a root file 
system during startup, this field should be set to the 
mount(3) equivalent date. This field is not updated if a file 
system is mounted read-only. The value of this field can be 
set and retrieved through calls to ioctl(2). See gd(7) for 
more details. 

bzb_tumount 

This field indicates the date the last umount(3) (or 
equivalent routine) call was made on the file system located 
on the corresponding partition. In some cases, such as root 
file system during shutdown, this field should be set to the 
umount(3) equivalent date. This field is not updated if an 
file system was mounted read-only. The value of this field 
can be set and retrieved through calls to ioctl(2). See 
gd(7) for more details. 

bzb_abm 

This field is the alternate block map structure for the associat- 
ed partition. See altblk(4) for more details about this 
structure. The value of this field can be retrieved through 
calls to ioctl(2). See gd(7) for more details. 
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SEE ALSO 

dp(lM), pname(lM), altblk(4), dpme(4), gd(7), au- 
torecovery(8). 
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NAME 

cml — configuration master list format 

DESCRIPTION 

The Configuration Master List (CML) defines each and every file 
in the standard A/UX product, and is used to produce and control 
the A/UX distributions. The CML is also used by au- 
torecovery(8), to bring the system up in (minimum) multiuser 
mode. 

The CML files are ASCII text files, containing one record (line) 
per filename entry, sorted in order by filename. Each record con- 
tains multiple tab-separated fields, describing a single file. Each 
field contains one or more subfields; if more than one, the 
subfields are separated by colons. The first subfield contains ei- 
ther a filename, a rule for determining the validity of the file, or 
textual information relating to the file. Additional subfields (if 
present) contain recognized values associated with the given rule. 

No field may be empty; that is, the first subfield must always con- 
tain at least one (nonblank) character. To indicate "no rule," the 
character - is used. Value subfields (that is, subfields past number 
1) may be null or missing if they do not apply in the given case. 
The subfields must occur in the specified order, however. Possible 
additional subfields are given in parentheses after each field name. 
For example, a partial record might contain 

- r:m /unix f - <>:100 =>:529799000 urroot... 

Currently there are 18 recognized fields in a record. 

1. master _rule 

A string field indicating the master rule for interpreting the 
validity of this file. The legal rules and their "valid if" con- 
ditions are 

$ If the first character of the master rule field is $, the 
field and subfield delimiters (normally tab and :) are 
substituted, respectively, by the characters represented 
by the four hex digits following the $; that is, if the first 
line contains $4 07c, the field and subfield separators 
will be @ (hex 40) and | (hex 7c). Any changes to these 
delimiters take effect immediately and remain in effect 
until the next $ change. The $ rule may be used at any 
point in the CML file where the field and subfield delim- 
iters must be changed. 
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# signifies a "no-op" condition; the remainder of this 
record is to be taken as a comment and no calculations 
are to be performed for any field. The # rule is a way to 
ignore information for a given file. 

Evaluate, in order, the remaining rules in this record to 
determine the validity of this file. 

2. autorecovery_rule [ : autorecovery_value] 

A string field indicating the autorecovery rule required for in- 
terpreting the validity of this file. The legal rules and their 
"valid if' conditions are 

r This file is required for autorecovery. 

- This file is not required for autorecovery. 

The following value is recognized. 

autorecovery _value 

A string indicating the type of use for which the au- 
torecovery rale applies. The legal value type is 

m Files which are necessary to bring the system up in 
multiuser mode. 

3. filename 

A string field containing the fully qualified filename of the 
file being described. A fully qualified filename starts with a 
slash and gives the unambiguous placement of the file in the 
directory hierarchy. (In some cases a filename can not be 
fully qualified. Any filename not beginning with a slash is 
assumed to describe a file that may occur in multiple direc- 
tories (such as .login). Such files are not used in au- 
torecovery.) 

4. filejype 

A string field containing the file type. The legal file types are 

d The file is a directory. 

f The file is a normal file. 

b The file is a block special file. 

c The file is a character special file. 

p The file is a named pipe. 

1 The file is a symbolic link. 
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s The file is a socket. 

linked Jilejiame 

If the file named by filename is a symbolic link (file_type== 
1), this field contains the fully qualified pathname of the file 
to which filename is linked If filename does not exist on 
startup, it is created by linking to linked Jile name. 

If the file named by filename is one of a set of multiple hard 
links (filejype* d && line count > 1), this field contains the 
fully qualified pathname of the aphabetically first file (ASCII 
sort order) of the set. If a file does not exist on startup and 
linked Jilename == filename, it is created by retrieving a 
copy from the eschatology file system. If a file does not exist 
on startup and linked Jilejiame * filename, it is created by 
linking to linked Jilename. 

If there is no linked Jilename, this field contains -. 

size_rule[ : size_yaluej : size_value_2) 
A string field indicating the size rule for interpreting the vali- 
dity of this file by examining its file length. The legal rules 
and their "valid if conditions are 

<> sizejninimum < actual Jile Jength < sizejnaximum 

== actual Jile Jength = size_exact 

0= actual Jile Jength = sizejsxact II actual Jile Jength = 

% sizejsxact - size_pct% < actual Jile Jength < sizejsxact 
+ sizejpct% 

no size rule, hence always true 

The following values are recognized. 

sizejvaluej 

This is a decimal number which contains the 
sizejninimum or sizejsxact depending on the sizejule 
specified. For files which do not have lengths (such as 
the special files) this value is always 0. 

size_value_2 

This is a decimal number which contains the 
sizejnaximum or sizejpet when required by the 
size rule, sizejpet is a decimal percentage (0 < sizejpet 
< 100). If the rule is <>, an empty field indicates that 
there is no set maximum limit. 
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7. time_rule[ : mtime_value] 

A string field indicating the time rule for interpreting the vali- 
dity of this file. The legal rules and their "valid if condi- 
tions are 

== actual jntime = mtime_value 

=> actual jntime > mtime_value 

- No time rule, hence always true. 

The following value is recognized. 

mtime_value 

A decimal number containing the appropriate 
modification time of the file, as required by the 
timejrule. 

8. ownership rule[ :file_user :file_group] 

A string field containing the ownership rule for determining 
the validity of this file. The legal rules and their "valid if" 
conditions are 

u actual jiser =file_user 

g actual_group =filej>roup 

b actual jiser =file_user && actual group =file_group 

- No ownership rule, hence always true. 

The following values are recognized. 

file_user 

A string containing the user name. 

filegroup 

A string field containing the group name. 

9. permissions _rule[ :file_mode] 

A string field containing the permission rule for determining 
the validity of this file. The legal rules and their "valid if" 
conditions are 

== actual Jilejnode =file_mode 

- No permissions rule, hence always true. 

The following value is recognized. 

filemode 

An octal numeric field containing the read/write and 
other file modes. Note that < jilejnode < 07777. 
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10. major _minor_rule[ : major juunber : minor jiumber] 

A string field indicating the major/minor rule for interpreting 
the validity of this file. The major minor rule , if specified, 
is ignored unless the file is a device (filejype = character 
ox file type = block) . The legal rules and their "valid if" 
conditions are 

actual jnajor juunber = major juunber && 
actual jninor juunber = minor juunber 

- Not a device, hence, always true. 

The following values are recognized. 

major juunber 

A decimal number containing the appropriate major 
device number required by the major jninor jule. 

minor juunber 

A decimal number containing the appropriate minor 
device number required by the major jninor jule. 

1 1 . version jule[ : version _value : version jninimum : version jnaximum] 
A string field indicating the version rule for interpreting the 
validity of this file by looking for a version number. If a file 

is made up of several modules, the version number used will 
be found in the "main" module, as part of a specifically for- 
matted "key version string." The legal rules and their 
"valid if' conditions are 

<> If version number is present, 

version jninimum < actual _yersionjiumber < 
version jnaximum 

== If version number is present, 

version jninimum = actual _versionjiumber 

version jnaximum, if defined, is ignored. 

*<> 

Version number must be present, and 

version jninimum < actual _yersionjiumber < 
version jnaximum 
*== 

Version number must be present, and 
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version jninimum = actual _yersion_number 
version jnaximum, if defined, is ignored. 

- No version rule, hence always true. 

The following values are recognized. 

version_value 

A string indicating the formats of version numbers 
which are possible for a file. The legal format type is 

s An SCCS (see sccs(l)) version number in a "key 
version string" of the following form 

@ (#) Copyright Apple Computer, Inc 198 6 Version 1.2 

which is produced by a string containing SCCS 
keywords as follows: 

%Z%Copyright Apple Computer, Inc 198 6\tVersion %I% 

where \t is a tab. 

version jninimum 

A string field containing the earliest allowable version 
number. 

version jnaximum 

A string field containing the maximum allowable ver- 
sion number. An empty field indicates that there is no 
maximum allowable version number limit 

12. checksum _rule[: checksum _yalue] 

A string field containing the checksum rule for interpreting 
the validity of this file by computing the checksum. The le- 
gal rule and its "valid if condition is 

s Compute and compare the checksum, using the algo- 
rithm of sum(l), which produces a 16-bit checksum. 

- No checksum rule, hence always true. 

The recognized value for this rule is 

checksum _value 

A decimal number containing the checksum value. An 
empty field, with no numeric value whatsoever, indi- 
cates that no checksum is to be computed. (The check- 
sum value of a zero-length file is 00000). 
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13. special _rule 

A string field indicating any special rules and values required 
for interpreting the validity of this file. (Reserved at this 
time). 

14. reserved_4 
Reserved for future use. 

15. reserved_3 
Reserved for future use. 

16. reserved_2 

Reserved for future use. 

17. reserved_l 
Reserved for future use. 

18. description 

A text field containing a description of the file. The descrip- 
tion field may be stored separately from the other fields in a 
special description file. In this case, each record in the 
description file will contain two tab-separated fields: the full 
pathname of the described file followed by a one line descrip- 
tion. The description file, like the rest of the CML will be 
sorted by filename. 

FILES 

/etc/eschatology/init2files 

Those files which are required by autorecovery. 

/etc/eschatology/otherfiles 

The balance of the CML (those files not required for au- 
torecovery). 

/etc/eschatology /descriptions 
The description file. 

SEE ALSO 

autorecovery(8). 
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NAME 

core — format of core image file 

DESCRIPTION 

The A/UX System writes out a core image of a terminated process 
when any of various errors occur. See signal(3) for the list of 
reasons; the most common are memory violations, illegal instruc- 
tions, bus errors, and user-generated quit signals. The core image 
is called core and is written in the process's working directory 
(provided it can be; normal access controls apply). A process with 
an effective user ID different from the real user ID will not pro- 
duce a core image. 

The first section of the core image is a copy of the system's per- 
user data for the process, including the registers as they were at 
the time of the fault. The size of this section depends on the 
parameter usize, which is defined in 

/usr/include/sys/param.h. The remainder represents 
the actual contents of the user's core area when the core image 
was written. If the text segment is read-only and shared, or 
separated from data space, it is not dumped. 

The format of the information in the first section is described by 
the user structure of the system, defined in 
/usr/include/sys/user.h. The important stuff not de- 
tailed therein is the locations of the registers, which are outlined in 
/usr/include/sys/reg.h. 

SEE ALSO 

setuid(2), signal(3). 
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NAME 

cpi o — format of cpi o archive 

DESCRIPTION 

The header structure, when the -c option of cpio(l) is not used, 
is: 

struct { 

short h_magic, 

h_dev; 
ushort h_ino, 

h_mode , 

h_uid, 

h_gid; 
short h_nlink, 

h_rdev , 

h_mtime [2] , 

h_namesize, 

h_filesize[2] ; 
char h_name [h_namesize rounded to word]; 
} Hdr; 

When the -c option is used, the header information is described 
by: 

sscanf (Chdr, "%6o%6o%6o%6o%6o%6o%6o%6o%lllo%6o%lllo%s", 
&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.h_gid, &Hdr .h_nlink, &Hdr.h_rdev, 
&Longtime, &Hdr .h_namesize, &Longf ile, Hdr .h_name) ; 

Longtime and Longfile are equivalent to Hdr.h_mtime 
and Hdr . h_f ilesize, respectively. The contents of each file 
are recorded in an element of the array of varying length struc- 
tures, archive, together with other items describing the file. 
Every instance of h_magic contains the constant 070707 (octal). 
The items h_dev through h_mtime have meanings explained in 
stat(2). The length of the null-terminated path name h_name, 
including the null byte, is given by h_namesi ze. 

The last record of the archive always contains the name 
trailer! ! !. Special files, directories, and the trailer are 
recorded with h_f ilesize equal to zero. 

SEE ALSO 

cpio(l), f ind(l), stat(2). 
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NAME 

dial up — modem escape sequence file 

DESCRIPTION 

/etc/dialup contains one or more entries describing the es- 
cape sequences for modems specified by the user (more informa- 
tion to follow), /etc/dialup also contains fields for error 
strings or error codes returned by modems after a command has 
been issued. If these fields are not set, the attributes will be set for 
an Apple modem by default 

The first symbol in an /etc/dialup entry must be an identifier 
which is taken from mt in remote(4). If an entry is longer than 
a single line, the lines in the entry must end with a "Y\ Com- 
mands can be one of the following abbreviations, followed by a 
"=" for a string command or *'#" for a numeric command, and 
then the appropriate command sequence for the particular modem. 

ag repeat the last command A/ 

as attention to signal for modem at 

at auto call unit type gene r i c 

cd return to command mode ; 

cr continuous redial X2 

dp dial up D 

ec echo command E 

em escape command +++ 

dm data mode O 

hu hang up line H 

vb verbal command returned from modem VI 

The following are return values from the modem if vb=vi: 

ok the previous command was OK ok 

ct the modem is connected and is online connect 

nc the modem has been disconnected NO CARRIER 

er the previous command is invalid error 

EXAMPLES 

If an entry in /etc/ remote looked like this: 

apple : br=1200 : at=generic :mt=apple 



February, 1990 

Revision C 



dialup(4) dialup(4) 



the corresponding entry in /etc/dialup might look like this: 

apple : as=AT : at=generic : dp=D : cr=X2 : \ 

hu=H : em=+++; ag=A/ ; ec=E; dm=0 : cd=; : ok=OK : \ 

ct=CONNECT : nc=NO CARRIER: er=ERROR: vb=Vl : 

FILES 

/etc/dialup 
/etc /remote 

SEE ALSO 

tip(lC), phones(4), remote(4). 
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NAME 

di r — format of System V directories 

SYNOPSIS 

♦include <sys/types.h> 
♦include <svf s/f sdir ,h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user 
may write into a directory. The fact that a file is a directory is in- 
dicated by a bit in the flag word of its inode entry (see f s(4)). 
The structure of a directory entry as given in the include file is: 



#ifndef 


SVFSDIRSIZ 


#define 


SVFSDIRSIZ 14 


#endif 




struct 


svfsdirect { 


ino t 


d ino; 


char 

}; 


d_name [SVFSDIRSIZ] ; 



By convention, the first two entries in each directory are for "." 
and ". .". The first is an entry for the directory itself. The second 
is for the parent directory. The meaning of ". ." is modified for 
the root directory of the master file system; there is no parent, so 
*'. ." has the same meaning as ".". 

SEE ALSO 

fs(4). 
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NAME 

disktab — disk description file 

SYNOPSIS 

♦include <disktab.h> 

DESCRIPTION 

disktab is a simple database that describes disk geometries. 
The format is patterned after the termcap(4) terminal database. 
Entries in di skt ab consist of a number of colon-separated fields. 
The first entry for each disk gives the names that are known for 
the disk, separated by I characters. The last name given should be 
a long name fully identifying the disk. 

The following list indicates the normal values stored for each disk 
entry: 

Name Type Description 

bl num Number of blocks per cylinder 

ns num Number of sectors per track 

nt num Number of tracks per cylinder 

nc num Total number of cylinders on the disk 

rg num Rotational gap 

This information is used by the newf s(lM) command. 

FILES 

/etc/disktab 

SEE ALSO 

newf s(lM), f s(4). 

BUGS 

This file shouldn't be necessary. Instead, the information should 
be stored on each disk. 
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NAME 

dpme — format of disk partition map entries 

SYNOPSIS 

♦include <apple/dpme.h> 

DESCRIPTION 

Starting at physical block 1 (offset 512 bytes) of each disk resides 
a disk partition map. This map describes the layout of the parti- 
tions for that disk. The disk partition map consists of one or more 
disk partition map entries. Each entry corresponds to at most one 
disk partition. The format of a disk partition map entry is: 



typedef struct 
{ 

ul6 














dpme_s i gn at u r e ; 










ul6 


dpme reserved 1; 










u32 


dpme_map entries; 










u32 


dpme_pblock_start; 










u32 


dpme_pb locks; 










DPIDENT 


dpme dpident; 










u32 


dpme_lblock start; 










u32 


dpme lblocks; 










u32 


dpme_re served 2: 


23; 


/* 


Bit 9 


through 31 


u32 


dpme os specific 1: 


1; 


/* 


Bit 8 


*/ 


u32 


dpme_os specific_2: 


1; 


/* 


Bit 7 


*/ 


u32 


dpme os pic code: 


1; 


/* 


Bit 6 


*/ 


u32 


dpme writable: 1, 




/* 


Bit 


5 */ 




u32 


dpme readable: 1 




/* 


Bit 


4 */ 




u32 


dpme bootable: 1 




/* 


Bit 


3 */ 




u32 


dpme in use: 1 




/* 


Bit 


2 */ 




u32 


dpme allocated: 1 




/* 


Bit 


1 */ 




u32 


dpme valid: 1 




/* 


Bit 


*/ 




u32 


dpme boot block; 










u32 


dpme boot bytes; 










u8 


*dpme_load_addr; 










u8 


*dpme load addr 2; 










u8 


*dpme_goto_addr; 










u8 


*dpme goto addr 2; 










u32 


dpme checksum; 










char 


dpme process id[16]; 










u32 


dpme boot args[32]; 










u32 


dpme reserved 3 [6 


2]; 
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} DPME; 

#define DPME_SIGNATURE 0x5 04d /* Signature value */ 
#define DPM_OFF 512 /* byte offset of dp map *, 
#define DPISTRLEN 32 

struct dpident 

{ 

char dpiname [DPISTRLEN]; /* name of partition */ 
char dpitype [DPISTRLEN]; /* type of partition */ 

}; 

typedef struct dpident DPIDENT; 

FIELD DESCRIPTIONS 

dpme_signature 

This field should always contain the magic number 

DPME_S I GNATURE . 

dpme_r e s e rved_l 

This field is not used by A/UX. 

dpme_map_ent r i e s 

This field indicates the size of the disk partition map meas- 
ured in units of disk partition map entries. Since each disk 
partition map entry is one block big, this field also indicates 
the number of blocks in the partition map. The value of this 
field is only meaningful for the first entry in the disk partition 
map. 

dpme_j?block_start 

This field indicates the physical block number of the starting 
block of the physical partition. 

dpme_pblocks 

This field indicates the number of physical blocks in the par- 
tition. This is usually referred to as the size of the physical 
partition. 

dpme_dpident 

This field is a structure that contains two string fields. The 
first field, dpiname, contains the name of the partition. 
The second field, dpitype, contains the type of the parti- 
tion. If the partition name (or type) is less than DPIS- 
TRLEN bytes long, it must be terminated by a null (binary 
zero) byte. An empty partition name or type (first byte 
null) is legal. These strings are case sensitive. 
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dpme_lblock_start 

For AAJX partitions, this field will always be zero. This field 
designates the first data block of the logical partition. 

dpme_lblocks 

This field designates the number of blocks in the data area of 
the partition. This is usually referred to as the size of the log- 
ical partition. For alternate bad blocking to occur it is neces- 
sary for the logical partition to be smaller than the physical 
partition. Those blocks between the end of the logical parti- 
tion and the end of the physical partition are usually used for 
alternate bad blocking. 

dpme_r e s e rved_2 

This field is not used by AAJX. 

dpme_os_speci f ic_l 

This field is not used by AAJX. 

dpme_os_specific_2 

This field is not used by AAJX. 

dpme_os_pic_code 

This field is not used by AAJX. 

dpme_writable 

This bit indicates that the creating/controlling operating sys- 
tem allows writing of the logical disk that comprises this par- 
tition. Whether or not the writing is allowed by other operat- 
ing systems and/or processors is not defined. Mainly infor- 
mative. 

dpme_readable 

This field is not used by AAJX. 

dpme_bootable 

This field is not used by AAJX. 

dpme_i n_u s e 

This field is not used by AAJX. 

dpme_allocated 

This bit indicates whether or not an operating system has laid 
claim to the partition described by this entry. 

dpme_valid 

This bit indicated whether or not this partition entry is valid 
or not 
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dpme_boot_block 

This field is not used by A/UX. 

dpme_bo o t_by t e s 

This field is not used by A/UX. 

dpme_load_addr 

This field is not used by A/UX. 

dpme_load_addr_2 

This field is not used by A/UX. 

dpme_goto_addr 

This field is not used by A/UX. 

dpme_go t o_addr_2 

This field is not used by A/UX. 

dpme_checksum 

This field is not used by A/UX. 

dpmej? r o ce s s_i d 

This field is not used by A/UX. 

dpme_boot_a rgs 

dpme_r e s e rved_3 

This field is not used by A/UX. 

SEE ALSO 

dp(lM), pname(lM), altblk(4), bzb(4), gd(7). 

FILES 

/dev/rdsk/c?d?s31 
/usr/include/apple/dpme . h 

BUGS 

It could be argued that the dpme_boot_args and 
dpme_signature fields would more appropriately be named 
dpme_o s_s pe c i f i c and dpme_ma gi c , respectively. 
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NAME 

dump . bsd — format of a file system dump 

SYNOPSIS 

♦include <sys/ types. h> 
♦include <sys/inode.h> 
♦include <dumprestor.h> 

DESCRIPTION 

The output of dump.bsd(lM) or the input for restore(lM) 
contains four distinct items: (1) a header record; (2) two groups of 
bit map records; (3) a group of records describing directories; and 
(4) a group of records describing files. 

The format of the header record and of the first record of each 
description is given in the include file <dumprestor . h>. 



#define 


NTREC 


20 


fdefine 


MLEN 


16 


tdefine 


MSIZ 


4096 


idefine 


TS TAPE 


: l 


#define 


TS INODE 2 


#define 


TS BITE 


; 3 


#define 


TS ADDR 4 


#define 


TS END 


5 


idefine 


TS_CLRI 


6 


#define 


MAGIC 


(int) 60011 


#define 


CHECKSUM (int) 84446 


struct 
{ 


spcl 




int 


c type; 




time t 


c_date; 




time t 


c ddate; 




int 


c volume; 




daddr t 


c tapea; 




ino t 


c i number; 




int 


c magic; 




int 


c checksum; 




struct 


dinode c dinode; 




int 


c count; 




char 


c_addr[BSIZE]; 


} spcl; 






struct 
{ 


idates 




char 


id name [16] ; 




char 


id incno; 




time t 


id ddate; 



}; 
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ntrec is the number of 1024 byte records in a physical block for 
the backup device. MLEN is the number of bits in a bit map word. 
MS I z is the number of bit map words. 

The TS_ entries are used in the c_type field to indicate what 
sort of header it is. The types and their meanings are as follows: 

T S_tap E Volume label. 

TS_IN0DE A file or directory follows. The c_dinode field 

is a copy of the disk inode and contains bits telling 

what sort of file it is. 
TS_BITS A bit map follows. This bit map has a 1 bit for 

each inode that was dumped. 
TS_ADDR A subrecord of a file description. (See c_addr 

later.) 
T S_end End of media record. 

TS_CLRI A bit map follows. This bit map contains a bit 

for all inodes that were empty on the file system 

when dumped. 
MAGIC All header records have this number in c_magic. 

CHECKSUM Header records checksum to this value. 

The fields of the header structure are as follows: 

c_type The type of the header. 

c_date The date the dump was taken. 

c_ddate The date the file system was dumped. 

c_volume The current volume number of the dump. 

c_t apea The current number of this (1024-byte) record. 

c_i number The number of the inode being dumped if of type 
TS_INODE. 

c_magic This contains the value MAGIC above, truncated 
as needed. 

c_checksum This contains whatever value is needed to make 
the record sum to CHECKSUM. 

c_dinode This is a copy of the inode as it appears on the file 
system (see f s(5)). 

c_count The count of characters in c_addr. 

c_addr An array of characters describing the blocks of the 

dumped file. A character is zero if the block asso- 
ciated with that character was not present on the 
file system, otherwise the character is nonzero. If 
the block was not present on the file system, no 
block was dumped; the block will be restored as a 
hole in the file. If there is not sufficient space in 
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this record to describe all of the blocks in a file, 
TS_ADDR records will be scattered through the 
file, each picking up where the last left off. 

Each volume, except the last, ends with a tapemark (read as an 
end of file). The last volume ends with a ts_end record and then 
the tapemark. 

The structure idates describes an entry in the file 
/etc/dumpdates where dump history is kept. The fields of 
the structure are 

id_name The name of dumped file system, /dev/id_name. 
id_incno The level number of the dump media (see 

dump . bsd(lM)). 
id_ddate The date of the incremental dump in system format 

(see types(5)). 

FILES 

/etc/dumpdates 

SEE ALSO 

dump . bsd(lM), restore(lM), f s(4), types(5). 
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NAME 

errf ile — error-log file format 

DESCRIPTION 

When hardware errors are detected by the system, an error record 
is generated and passed to the error-logging daemon for recording 
in the error log for later analysis. The default error log is 

/usr/adm/errfile. 

The format of an error record depends on the type of error that 
was encountered. Every record, however, has a header with the 
following format: 

struct errhdr { 

short e_type; /* record type */ 

short e_len; /* bytes in record (inc hdr) */ 

time_t e_time; /* time of day */ 

}; 

The permissible record types are as follows: 

#define E_GOTS 010 /* start for the UNIX/TS */ 

#define E_GORT Oil /* start for the UNIX/RT */ 

tdefine E_STOP 012 /* stop */ 

#define E_TCHG 013 /* time change */ 

#define E_CCHG 014 /* configuration change */ 

#define E_BLK 020 /* block device error */ 

#define E_STRAY 030 /* stray interrupt */ 

#define E_PRTY 031 /* memory parity */ 

Some records in the error file are of an administrative nature. 
These include the startup record that is entered into the file when 
logging is activated, the stop record that is written if the daemon is 
terminated "gracefully", and the time-change record that is used 
to account for changes in the system's time-of-day. These records 
have the following formats: 

struct estart { 

short e_cpu; /* CPU type */ 

struct utsname e_name; /* system names */ 

}; 

tdefine eend errhdr /* record header */ 

struct etimchg { 

time_t e_ntime; /* new time */ 
>; 

Stray interrupts cause a record with the following format to be 
logged: 

struct estray { 

uint e_saddr; /* stray loc or device addr */ 

}; 
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Generation of memory subsystem errors is not supported in this 
release. 

Error records for block devices have the following format 

struct eblock { 

dev_t e_dev; /* * 'true' ' major + minor 

dev no */ 
physadr e_regloc; /* controller address */ 
short e_bacty; /* other block I/O 

activity */ 

/* number read/writes */ 

/* number ' 'other' ' operations */ 

/* number unlogged errors */ 
} e_stats; 

short e_bflags; /* read/write, error, etc */ 

short e_cyloff; /* logical dev start cyl */ 

daddr_t e_bnum; /* logical block number */ 

ushort e_bytes; /* number bytes to transfer */ 

paddr_t e_memadd; /* buffer memory address */ 

ushort e_rtry; /* number retries */ 

short e nreg; /* number device registers */ 



struct iostat { 

long io_ops; 
long io_misc; 
ushort io unlog; 



}; 



The following values are used in the e_bf lags word: 

#define E_WRITE /* write operation */ 

#define E_READ 1 /* read operation */ 

#define E_NOIO 02 /* no I/O pending */ 

#define E_PHYS 04 /* physical I/O */ 

#define E_FORMAT 010 /* Formatting Disk*/ 

#define E_ERROR 020 /* I/O failed */ 

SEE ALSO 

errdemon(lM). 
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NAME 

ethers — Ethernet address to hostname database or YP domain 

DESCRIPTION 

The /etc/ethers file contains information regarding the 
known (48 bit) Ethernet addresses of hosts on the Internet. For 
each host on an Ethernet, a single line should be present with the 
following items of information: 

ethernet-address hostname 

Items are separated by any number of blanks and/or tabs. Use # 
to introduce a single line or midline comment. 

The standard form for ethernet-address is x:x:x:x:x:x: where x is a 
hexadecimal number between and 255, representing one byte. 
The address bytes are always in network order, hostname may 
contain any printable character other than a space, tab, newline, or 
comment character. The hostnames in the ethers file should 
correspond to the hostnames in the /etc/hosts file (see 
hosts(4)). 

The ether JineQ routine from the Ethernet address manipulation 
library, ethers(3N) may be used to scan lines of the ethers 
file. 

FILES 

/etc/ethers 

SEE ALSO 

ethers(3N), hosts(4). 



February, 1990 

Revision C 



exports(4) exports(4) 



NAME 

exports — NFS file systems being exported 

SYNOPSIS 

/etc/exports 

DESCRIPTION 

The file /etc /exports describes the file systems which are be- 
ing exported to NFS clients. It is created by the system adminis- 
trator using a text editor and processed by the mount request dae- 
mon mount d(lM) each time a mount request is received. 

The file consists of a list of file systems and the netgroup(4) or 
machine names allowed to remote mount each file system. The 
file system names are left justified and followed by a list of names 
separated by white space. The names will be looked up in 
/etc/netgroup and then in /etc/hosts. A file system 
name with no name list following means export to everyone. A 
"#" anywhere in the file indicates a comment extending to the 
end of the line it appears on. 

EXAMPLES 

/usr clients # export to my clients 

/usr/local # export to the world 

/usr phoenix sun sundae # export to only these 

machines 



FILES 

/etc/exports 

SEE ALSO 

mountd(lM), netgroup(4). 
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NAME 

f ilehdr — file header for common object files 

SYNOPSIS 

♦include <f ilehdr. h> 

DESCRIPTION 

Every common object file begins with a 20-byte header. The fol- 
lowing C struct declaration is used. 



magic number */ 
number of sections */ 
time & date stamp */ 
file ptr to symtab */ 
# symtab entries */ 
sizeof{opt hdr) */ 
flags */ 



struct filehdr 
{ 

unsigned short 






f magic ; 


/ 


unsigned short 


f nscns ; 


/ 


long 


f timdat ; 


/ 


long 


f symptr ; 


/ 


long 


f nsyms ; 


/ 


unsigned short 


f opthdr ; 


/ 


unsigned short 


f flags ; 


/ 



f_symptr is the byte offset in the file at which the symbol table 
can be found. Its value can be used as the offset in f seek(3S) to 
position an I/O stream to the symbol table. See a out hdr (4) for 
the structure of the optional a . out header. The valid magic 
number is 



#define MC68MAGIC 0520 



/* magic number */ 



The value in f_timdat is obtained from the time(2) system 
call. Flag bits currently defined are 

relocation entries stripped */ 
file is executable */ 
line numbers stripped */ 
local symbols stripped */ 
minimal object file */ 
update file, ogen produced */ 
file is "pre-swabbed" */ 
16-bit DEC host */ 
32-bit DEC host */ 
non-DEC host */ 
"patch" list in opt hdr */ 
"patch" list in opt hdr */ 



# define 


F RELFLG 


00001 


/ 


#define 


F EXEC 


00002 


/ 


#define 


F LNNO 


00004 


/ 


tdefine 


F_LSYMS 


00010 


/ 


#define 


F MINMAL 


00020 


/ 


# define 


F_UPDATE 


00040 


/ 


tdefine 


F SWABD 


00100 


/ 


tdefine 


F_AR1 6WR 


00200 


/ 


tdefine 


F AR32WR 


00400 


/ 


# define 


F_AR32W 


01000 


/ 


# define 


F PATCH 


02000 


/ 


#define 


F NODF 


02000 


/ 



SEE ALSO 

time(2), f seek(3S), a . out(4), aouthdr(4). 
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NAME 

f installrc — f install default configuration file 

SYNOPSIS 

/etc/ f install re 

DESCRIPTION 

You can use the . f installrc and /etc/f installrc files 
to specify the default options used with finstall, such as 
whether finstall should prompt for which floppy drive to use. 
The variables that can be set for finstall are as follows: 

CTL_ASKDRIVE 

determines if finstall should prompt for which floppy 
drive to use. 

CTL_ASKINSTALL 

determines if finstall should prompt for the directory to 
install the software under. 

CTL_CHECKSPACE 

determines if finstall should check for enough space to 
install the software. 

CON_TRIES 

specifies the number of times allotted to attempt to answer a 
prompt 

CTL_ALLOWRC 

determines whether the . f installrc file should be used. 

CTL_TAKEDEFAULT 

determines if finstall should use default answers. 
The default values for these variables are as follows: 

CTL_ASKDRIVE =1 

CTL_ASKINSTALL =1 

CTL_CHECKSPACE =1 

CON_TRIES =5 

CTL_ALLOWRC =1 

CTL_TAKEDEFAULT =0 

You can change the value of the default variables with results 
described as follows: 

CTL_ASKDRIVE 

!= 0: instructs finstall to prompt for which floppy drive 
to use for installation. 
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= 0: instructs f install to use the right-hand floppy drive 
for installation. 

CTL_ASKINSTALL 

!= 0: instructs finstall to prompt for the installation 
directory. 

= 0: instructs finstall to use the directory specified by 
the software developer as the default installation directory. If 
the software developer did not specify a directory, fin- 
stall uses the current working directory as the installation 
directory. 

CTL_CHECKSPACE 

!= 0: instructs finstall to check for enough space on the 
installation directory to install the software. 
= 0: instructs finstall to proceed with installation 
without checking for available space. 

CON_TRIES 

— n: n specifies the number of times allotted to attempt to 
answer a prompt 

CTL_ALLOWRC 

!= 0: instructs finstall to not use a . f installrc file 
in the current working directory. 

= 0: instructs finstall to use a . f installrc file in 
the current working directory. 

CTL_TAKEDEFAULT 

!= 0: instructs finstall to print the prompt on the screen 

but to use the default answer rather than waiting for a user 

response. 

= 0: instructs finstall to print the prompt on the screen 

and wait for a response from the user. 

FILES 

/etc/ f installrc 
.f installrc 

SEE ALSO 

finstall(lM). 
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NAME 

fs — file systems 

DESCRIPTION 

A/UX® supports System V file systems (SVFS) and Berkeley 4.2 
file systems (UFS). (See svf s(4) and uf s(4) for details about 
file-system organization.) A/UX does not support Macintosh® 
file systems as mountable file systems. However, the A/UX finder 
may read and write these file systems. Please see Inside Macin- 
tosh, Volume II for a description of the original Macintosh file sys- 
tem and Inside Macintosh, Volume IV for a description of the 
hierarchical file system (HFS). 

mkf s is used to create SVFS file sy terns. 

newf s is used to create UFS file systems, tunef s can be used 
to change the dynamic parameters of a UFS. 

SEE ALSO 

mkf s(lM), newf s(lM), tunef s(lM), svf s(4), uf s(4). 
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NAME 

f spec — syntax for format lines for newform 

DESCRIPTION 

It is sometimes convenient to maintain text files on the A/UX sys- 
tem with nonstandard tabs, (i.e., tabs which are not set at every 
eighth column). Such files must generally be converted to a stan- 
dard format, frequently by replacing all tabs with the appropriate 
number of spaces, before they can be processed by A/UX system 
commands. A format specification occurring in the first line of a 
text file specifies how tabs are to be expanded in the remainder of 
the file. 

A format specification consists of a sequence of parameters 
separated by blanks and surrounded by the brackets < : and : > 
Each parameter consists of a keyletter, possibly followed immedi- 
ately by a value. The following parameters are recognized: 

ttabs The t parameter specifies the tab settings for the file. 
The value of tabs must be one of the following: 

1. a list of column numbers separated by commas, in- 
dicating tabs set at the specified columns; 

2. a - followed immediately by an integer n, indicat- 
ing tabs at intervals of n columns; 

3. a - followed by the name of a "canned" tab 
specification. 

Standard tabs are specified by t-8, or equivalently, 
tl, 9, 17, 25, etc. The canned tabs which are recog- 
nized are defined by the tabs (1) command. 

ssize The s parameter specifies a maximum line size. The 
value of size must be an integer. Size checking is per- 
formed after tabs have been expanded, but before the 
margin is prefixed. 

Twnargin The m parameter specifies a number of spaces to be 
prefixed to each line. The value of margin must be an 
integer. 

d The d parameter takes no value. Its presence indicates 

that the line containing the format specification is to be 
deleted from the converted file. 

e The e parameter takes no value. Its presence indicates 

that the current format is to prevail only until another 
format specification is encountered in the file. 
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Default values, which are assumed for parameters not supplied, 
are t-8 and mO. If the s parameter is not specified, no size 
checking is performed. If the first line of a file does not contain a 
format specification, the above defaults are assumed for the entire 
file. The following is an example of a line containing a format 
specification: 

* <:t5,10,15 s72:> * 

If a format specification can be disguised as a comment, it is not 
necessary to code the d parameter. 

SEE ALSO 

ed(l), newf orm(l), tabs(l). 
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NAME 

f stab — static information about file systems 

SYNOPSIS 

tinclude <mntent . h> 

DESCRIPTION 

The file /etc/ f stab describes the file systems and swapping 
partitions used by the local machine. It can be modified with a 
text editor by the system administrator. The file is read by com- 
mands that mount, unmount, and check the consistency of file sys- 
tems; it is also read by the system in providing swap space. Be- 
cause there is an appropriate mount request in the /etc /re 
startup file, any file systems described in /etc/fstab (other 
than those of type ignore or with mount option noauto) are 
mounted automatically whenever multi-user mode is entered. 

The /etc/fstab file consists of a number of lines in the follow- 
ing format 

fsname dir type optsfreq passno 

For example 

/dev/xyOa / 5.2 rw,noquota 1 2 

The field freq is optionally used by dump . bsd(lM) to help report 
which file systems need to be dumped, passno is used by 
f sck(lM) to help select which file systems to check. For exam- 
ple, fsck -p2 checks all the 5.2 file systems listed in 
/etc/fstab with passno greater than or equal to 2. 

The entries from this file are accessed using the routines in 
getmntent(3), which returns a structure of the following form: 



struct mntent { 








char 


*mnt fsname; 


/* 


file system name */ 




char 


*mnt dir; 


/* 


file system path prefix 


*/ 


char 


*mnt type; 


/* 


4.2, 5.2, nfs, swap, 
or ignore */ 




char 


*mnt opts; 


/* 


rw, ro, noquota, quota, 
hard, soft */ 


noauto, 


int 


mnt freq; 


/* 


dump frequency, in days 


*/ 


int 


mnt passno; 


/* 


pass # on parallel fsck 


*/ 



}; 

Fields are separated by white space; a # as the first nonwhite char- 
acter indicates a comment. 
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The mnt_type field determines how the mnt_f sname and 
mnt_opt s fields will be interpreted. Here is a list of the file sys- 
tem types currently supported, and the way each of them interprets 
these fields. 

4.2/5.2 
mnt_f sname Must be a block device. 

mnt_opts Valid options are ro, rw, quota, no- 

quota, noauto. 

NFS 

mnt_f sname The path on the server of the directory to 

be served. 

mnt_opts Valid options are ro, rw, quota, no- 

quota, noauto, hard, soft. 

SWAP 

mnt_f sname Must be a block device swap partition. 

mnt_opts Ignored. 

If the mnt_opts field contains noauto, the entry will be ig- 
nored during a mount -a command, allowing definition of 
f stab entries for commonly used file systems not mounted au- 
tomatically. 

If the mnt_type is specified as ignore then the entry is ig- 
nored. This is useful to show disk partitions not currently used. 

The /etc/f stab file is only read by programs and never writ- 
ten by them; it is the duty of the system administrator to maintain 
this file. The order of records in /etc/f stab is important be- 
cause f sck, mount, and umount process the file sequentially; 
file systems must appear following the file systems they are 
mounted in. 

Note that listing a file system as type swap will not cause the sys- 
tem to mount the file system as a swap area; to do that, you must 
use the swap command. 

FILES 

/etc/fstab 

SEE ALSO 

dump . bsd(4), f sck(lM), mount(lM), swap(lM), 
getmntent(3). 
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NAME 

f stypes — name-mapping information for file systems 

SYNOPSIS 

♦include <sys/fstypent .h> 

DESCRIPTION 

/etc/f stypes contains information about file-system types. It 
can be modified by the system administrator using a text editor. 
The file is used by commands that need to know the type of a 
specified file system. It is also used by commands to determine 
the location of file-system-dependent utilities. 

The /etc/f stypes file consists of lines in the following for- 
mat: 

numeric-type name-list [pathname-list] 

For example: 

5.2,svfs,s5 /etc/fs/5.2:/etc/fs/svfs 

The fields are separated by white space; a # as the first character 
indicates a comment. A # after name-list or path-list indicates 
that the rest of the line is a comment 

The placeholder numeric-type is the integer type that is passed to 
fsmount. See f smount(2). These are defined in 
<sys /mount. h>. The name-list is a comma-separated list of 
character strings that describe the file-system type. At least one of 
these is defined in <mntent . h>. The pathname-list is a colon- 
separated list of pathnames. These pathnames indicate where util- 
ity programs associated with the file-system type reside. If this 
field is empty, the default location is /etc/f s /name-list. 

The entries in this file are accessed using f stypent, which reads 
the next entry from the file and returns a pointer to a struct 
f stypent . This structure is defined in <sys/f stypent>as: 

struct fstypent { 
int fstype; 
char **typelist; 
char *pathlist; 
}; 
FILES 

/etc/fstypes 
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SEE ALSO 

getmntent(3), f stypent(3), f s(4), f stab(4). 
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NAME 

gettydef s — speed and terminal settings used by getty 

DESCRIPTION 

The /etc /gettydef s file contains information used by 
getty(lM) to set up the speed and terminal settings for a line. It 
supplies information on what the login prompt should look like. 
It also supplies the speed to try next if the user indicates the 
current speed is not correct by typing an interrupt character. 

Each entry in /etc /gettydef s has the following format 

label# initial-flags # final-flags # flow-control # login-prompt #next-label 

Each entry is followed by a blank line. The various fields can 
contain quoted characters of the form \b, \n, \c, etc., as well as 
\nnn, where nnn is the octal value of the desired character. The 
various fields are: 

label This is the string against which getty tries to 

match its second argument. It is often the speed, 
such as 1200, at which the terminal is supposed 
to run, but it need not be (see below). 

initial-flags These flags are the initial ioctl(2) settings to 
which the terminal is to be set if a terminal type is 
not specified to getty. The flags that getty 
understands are the same as the ones listed in 
/usr/include/sys/termio.h (see ter- 
mio(7)). Normally only the speed flag is required 
in the initial-flags, getty automatically sets the 
terminal to raw input mode and takes care of most 
of the other flags. The initial-flag settings remain 
in effect until getty executes login(l). 

final-flags These flags take the same values as the initial-flags 
and are set just prior to getty executes login. 
The speed flag is again required. The composite 
flags sane or SANE2 take care of most of the oth- 
er flags that need to be set so that the processor and 
terminal are communicating in a rational fashion. 
The other two commonly specified final-flags are 
tab 3, so that tabs are sent to the terminal as 
spaces, and HUPCL, so that the line is hung up on 
the final close. Flag attributes are added from left 
to right, flags that start with a ~ are subtracted, e.g., 
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SANE "PARENB. This field specifies what type of 
flow control to use on the line. The currently al- 
lowed settings are apple (for apple flow control), 
dtr (for DTR flow control), modem (for modem 
control), and FLOW (for hardware flow control). 
These modes can also be turned off by using the ~ 
as a prefix. 

login-prompt This entire field is printed as the login-prompt. Un- 
like the above fields where white space is ignored 
(a space, tab or newline), they are included in the 
login-prompt field. 

next-label If this entry does not specify the desired speed, in- 
dicated by the user typing a Break character, then 
getty will search for the entry with next-label as 
its label field and set up the terminal for those set- 
tings. Usually, a series of speeds are linked togeth- 
er in this fashion, into a closed set; For instance, 
2400 linked to 1200, which in turn is linked to 
300, which finally is linked to 24 00. 

If getty is called without a second argument, then the first entry 
of /etc/gettydefs is used, thus making the first entry of 
/etc/gettydef s the default entry. It is also used if getty 
can not find the specified label. If /etc/gettydefs itself is 
missing, there is one entry built into the command which will 
bring up a terminal at 300 baud. 

It is strongly recommended that after making or modifying 
/etc/gettydefs, it be run through getty with the check op- 
tion to be sure there are no errors. 

The following four symbols define the SANE state. 



# define ISANE (BRKINT | IGNPAR | ISTRIP | ICRNL 

# define OSANE (OPOST | ONLCR) 

# define CSANE (CS7 | PARENB | CREAD) 

# define LSANE (ISIG | ICANON | ECHO | ECHOK) 

FILES 

/etc/gettydefs 



IXON) 
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SEE ALSO 

login(l), getty(lM), ioctl(2), termio(7). 



February, 1990 

Revision C 



group(4) group(4) 



NAME 

group — group file 

SYNOPSIS 

/etc/group 

DESCRIPTION 

group contains for each group the following information: 

• group name 

• encrypted password 

• numerical group ID 

• a comma separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each 
group is separated from the next by a newline. If the password 
field is null, no password is demanded. 

This file resides in the /etc directory. Because of the encrypted 
passwords, it can and does have general read permission and can 
be used, for example, to map numerical group ID's to names. 

A group file can have a line beginning with a plus (+), which 
means to incorporate entries from the yellow pages. There are 
two styles of + entries: All by itself, + means to insert the entire 
contents of the yellow pages group file at that point; +name means 
to insert the entry (if any) for name from the yellow pages at that 
point If a + entry has a nonnull password or group member field, 
the contents of that field will overide what is contained in the yel- 
low pages. The numerical group ID field cannot be overridden. 

EXAMPLES 

+mypro ject : : :carolyn, Jennifer 
+ : 

If these entries appear at the end of a group file, then the group 
mypro ject will have members carolyn and Jennifer, and 
the password and group ID of the yellow pages entry for the group 
mypro ject. All the groups listed in the yellow pages will be 
pulled in and placed after the entry for mypro ject . 

FILES 

/etc/group 
/etc/yp/group 
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SEE ALSO 

passwd(l), setgroups(2), crypt(3), initgroups(3), 
passwd(4). 

BUGS 

The passwd(l) command won't change group passwords. 
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NAME 

HOSTNAME — hostname and domainname database 

DESCRIPTION 

HOSTNAME resides in the /etc directory and consists of one line 
containing the following items of information 

hostname domainname 

Items are separated by any number of blanks and/or tabs. There 
must be no white space at the beginning of the line. 

hostname is the name of the local host machine and domainname 
is the name of the Yellow Pages domain on which the local host 
resides. 

EXAMPLES 

magic apple 

FILES 

/etc/HOSTNAME 

SEE ALSO 

hostname(l), domainname(l), chgnod(lM). 

A/UX Installation Guide 

RFC-882, RFC-883, RFC-920, RFC-921, RFC-952, RFC-953, 

RFC-973, RFC-974 (DNN Network Information Center, SRI 

International) 
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NAME 

hosts — host name database 

DESCRIPTION 

The hosts file contains information regarding the known hosts 
on the DARPA Internet For each host a single line should be 
present with the following information: 

official host name 
Internet address 
aliases 

Items are separated by any number of blanks or tab characters. A 
# indicates the beginning of a comment; characters up to the end 
of the line are not interpreted by routines which search the file. 
This file is normally created from the official host data base main- 
tained at the Network Information Control Center (NIC), though 
local changes may be required to bring it up to date regarding 
unofficial aliases and unknown hosts. 

Network addresses are specified in the conventional . notation us- 
ing the inet_addr ( ) routine from the Internet address manipu- 
lation library, inet(3N). Host names may contain any printable 
character other than a field delimiter, newline, or comment charac- 
ter. 

FILES 

/etc/hosts 
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NAME 

hosts . equiv — list of trusted hosts 

DESCRIPTION 

hosts. equiv resides in directory /etc and contains a list of 
trusted hosts. When an rlogin(l) or remsh(l) request from 
such a host is made, and the initiator of the request is in 
/etc/passwd, then no further validity checking is done. That 
is, rlogin does not prompt for a password, and remsh com- 
pletes successfully. So a remote user is "equivalenced" to a local 
user with the same user ID when the remote user is in 
hosts. equiv. 

The format of hosts . equiv is a list of names, as in this exam- 
ple: 

hostl 
host2 
+@groupl 
-@group2 

A line consisting of a simple host name means that anyone log- 
ging in from that host is trusted. A line consisting of +@group 
means that all members of that network group are trusted. A line 
consisting of -@ group means that members of that group are not 
trusted. Programs scan hosts. equiv linearly, and stop at the 
first hit (either positive for hostname and +@ entries, or negative 
for -@ entries). A line consisting of a single + means that every- 
one is trusted. 

The .rhosts file has the same format as hosts. equiv. 
When user x executes rlogin or remsh, the .rhosts file 
from X y s home directory is conceptually concatenated onto the 
end of hosts. equiv for permission checking. However, -@ 
entries are not sticky. If a user is excluded by a minus entry from 
hosts . equiv but included in . rhosts, men that user is con- 
sidered trusted. In the special case when the user is root, then 
only the / . rhosts file is checked. 

It is also possible to have two entries (separated by a single space) 
on a line of these files. In this case, if the remote user is 
equivalenced by the first entry, then that user is allowed to log in 
as any member of the second entry. Thus 

sundown John 
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allows anyone from sundown to log in as j ohn, and 

+@groupl +@group2 

allows any member of netgroupl to log in as a member of net- 
group2. 

FILES 

/etc/hosts . equiv 

SEE ALSO 

rlogin(l), remsh(l), netgroup(4). 
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NAME 

inittab — script for the init process 

DESCRIPTION 

The inittab file supplies the script for the role init plays as a 
general process dispatcher. The process that constitutes the ma- 
jority of the process dispatching activities of init is the line pro- 
cess /etc/getty that initiates individual terminal lines. Other 
processes typically dispatched by init are daemons and the 
shell. 

The inittab file is composed of entries that are position depen- 
dent and have the following format 

id: r state : action : process 

Each entry is delimited by a newline; however, a backslash (\) 
preceding a newline indicates a continuation of the entry. Up to 
512 characters per entry are permitted. Comments may be insert- 
ed in the process field using the sh(l) convention for comments. 
Comments for lines that spawn getty processes are displayed by 
the who(l) command. It is expected that they will contain some 
information about the line, such as the location. There are no lim- 
its, other than maximum entry size, imposed on the number of en- 
tries within the inittab file. The entry fields are 

id This is one to four characters used to uniquely identify 

an entry. 

rstate This defines the run level in which this entry is to be pro- 
cessed. The entry, run levels effectively corresponds to 
a configuration of processes in the system. That is, each 
process spawned by init is assigned a run level or run 
levels in which it is allowed to exist. The run levels are 
represented by a number ranging from through 6. As 
an example, if the system is in run level 1, only those en- 
tries having a 1 in the rstate field will be processed. 
When init is requested to change run levels, all 
processes which do not have an entry in the rstate field 
for the target run level will be sent the warning signal 
(SIGTERM) and allowed a 20-second grace period be- 
fore being forcibly terminated by a kill signal (SIG- 
kill). The rstate field can define multiple run levels 
for a process by selecting more than one run level in any 
combination from 0-6. If no run level is specified, then 
the process is assumed to be valid at all run levels 0-6. 
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There are three other values, a, b, and c, which can ap- 
pear in the rstate field, even though they are not true 
run levels. Entries which have these characters in the 
rstate field are processed only when the init (see 
init(lM)) process requests them to be run (regardless 
of the current run level of the system). They differ from 
run levels in that init can never enter run level a, b, or 
c. Also, a request for the execution of any of these 
processes does not change the current run level. Furth- 
ermore, a process started by an a, b, or c command is 
not killed when init changes levels. They are only 
killed if their line in /etc/inittab is marked off in 
the action field, their line is deleted entirely from 
/etc/inittab, or init goes into the SINGLE USER 
state. 

action Key words in this field tell init how to treat the pro- 
cess specified in the process field. The actions recog- 
nized by init are as follows: 

re spawn If the process does not exist, then start 

the process (do not wait for its termi- 
nation, that is, continue scanning the 
init tab file), and when it dies res- 
tart the process. If the process current- 
ly exists, then do nothing and continue 
scanning the init tab file. 

wait When init enters the run level that 

matches the entry's rstate, start the 
process and wait for its termination. 
All subsequent reads of the inittab 
file while init is in the same run lev- 
el will cause init to ignore this en- 
try. 

once When init enters a run level that 

matches the entry's rstate, start the 
process, do not wait for its termina- 
tion. When it dies, do not restart the 
process. If upon entering a new 
run level, where the process is still 
running from a previous run level 
change, the program will not be res- 
tarted. 
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boot 



bootwait 



powerfail 



powerwait 



off 



ondemand 



The entry is to be processed only at 
the boot-time read of the inittab 
file, init is to start the process, not 
wait for its termination; and when it 
dies, not restart the process. In order 
for this instruction to be meaningful, 
the rstate should be the default or it 
must match init's run level at boot 
time. This action is useful for an ini- 
tialization function following a 
hardware reboot of the system. 

The entry is to be processed only at 
the boot-time read by init of the 
inittab file, init is to start the 
process, wait for its termination and, 
when it dies, not restart the process. 

Execute the process associated with 
this entry only when init receives a 
power fail signal (SIGPWR see si g- 
nal(3)). 

Execute the process associated with 
this entry only when init receives a 
power fail signal (SIGPWR) and wait 
until it terminates before continuing 
any processing of inittab. 

If the process associated with this en- 
try is currently running, send the warn- 
ing signal (SIGTERM) and wait 20 
seconds before forcibly terminating 
the process via the kill signal (SIG- 
KILL). If the process is nonexistent, 
ignore the entry. 

This instruction is really a synonym 
for the re spawn action. It is func- 
tionally identical to re spawn but is 
given a different keyword in order to 
divorce its association with run levels. 
This is used only with the a, b, or c 
values described in the rstate field. 
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initdefault An entry with this action is only 
scanned when init is initially in- 
voked, init uses this entry, if it ex- 
ists, to determine which run level to 
enter initially. It does this by taking 
the highest run level specified in the 
rstate field and using that as its ini- 
tial state. If the rstate field is empty, 
this is interpreted as 0123456 and so 
init will enter run level 6. Also, the 
initdefault entry can use s to 
specify that init start in the SINGLE 
USER state. Additionally, if init 
does not find an initdefault entry 
in /etc/inittab, then it will re- 
quest an initial run level from the user 
at reboot time. 

sysinit Entries of this type are executed be- 

fore init tries to access the console. 
It is expected that this entry will be 
used only to initialize devices on 
which init might try to ask the run 
level question. These entries are exe- 
cuted and waited for before continu- 
ing. 

process This is a sh command to be executed. The entire pro- 
cess field is prefixed with exec and passed to a forked 
shas 

sh -c 'exec command* 

For this reason, any legal sh syntax can appear in the 
process field. Comments can be inserted with the # 
comment syntax. 

FILES 

/etc/inittab 

SEE ALSO 

sh(l), who(l), getty(lM), exec(2), open(2), signal(3). 
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NAME 

inode — format of a System V inode 

SYNOPSIS 

#include <sys/types.h> 
#include <svfs/inode.h> 

DESCRIPTION 

An inode for a plain file or directory in a file system has the fol- 
lowing structure defined by <svf s/ inode . h>. 

/* Inode structure as it appears on a disk block. */ 
struct dinode { 

ushort di_mode; /* mode and type of file */ 

short di_nlink; /* number of links to file * 

ushort di_uid; /* owner' s user ID */ 

ushort di_gid; /* owner's group ID */ 

off_t di_size; /* number of bytes in file * 

char di_addr [40] ; /* disk block addresses */ 

#define di_gen; di_addr[39] 

time_t di_atime; /* time last accessed */ 

time_t di_mtime; /* time last modified */ 

time_t di_ctime; /* time created */ 

}; 

/* 

* the 40 address bytes: 

* 39 used; 13 addresses 

* of 3 bytes each. 
*/ 

For the meaning of the defined types of f_t and time_t see 
types(5). 

FILES 

/usr/include/svf s/inode . h 

SEE ALSO 

stat(2), fs(4), types(5). 
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NAME 

ioctl . syscon — console terminal settings file 

SYNOPSIS 

/etc/ioctl . syscon 

DESCRIPTION 

The file /etc/ioctl. syscon contains information about the 
ioctl states of the A/UX virtual terminal console. This file is 
created by init(lM) when the system is put into single-user 
mode, and it is read by the init process when init first comes 
up. 

The information contained in /etc/ioctl . syscon is used to 
set the terminal modes on the initial console emulator. It is used 
primarily to preserve reasonable values for terminal settings 
across system reboots (instead of using the driver-imposed de- 
faults). 

The ioctl. syscon file consists of 16 colon-separated fields, 
closely resembling the output of the command 

stty -g 

For example, a sample /etc/ioctl. syscon file looks like 
this: 

526:5:bd:3b:0:3:lc:7f : 15 : 4 : : : : : : 

while the stty -g command on the console terminal would pro- 
duce the following output: 

526:5: bd: 3b: 3 : lc : 7f : 15 : 4 : : : 

The primary difference is that the ioctl . syscon file contains 
four additional fields corresponding to the termcb structure, an 
undocumented artifact of System III. These four fields are always 
zero. The remaining fields correspond to the fields of the ter- 
mio structure; for an explanation of these fields, see termio(7). 

If the /etc/ioctl . syscon file becomes damaged, the system 
may refuse to accept input from the console terminal during the 
boot process. To remedy this situation, it is safest simply to re- 
move the file altogether from within the A/UX Startup shell en- 
vironment, allowing the default settings to be established once 
again. The driver defaults are reasonable and will allow the sys- 
tem to boot successfully. A corrected version of the file will then 
be generated when the system is booted into multi-user mode. See 
Startups hell (8) for details on performing A/UX file system 
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operations from the A/UX Startup shell. 

FILES 

/etc/ioctl . syscon 

SEE ALSO 

stty(l), init(lM), termio(7), StartupShell(8). 



February, 1990 

Revision C 



issue(4) issue(4) 



NAME 

issue — issue identification file 

DESCRIPTION 

The file /etc/issue contains the issue or project 
identification to be printed as a login prompt. This is an ASCII 
file which is read by program getty and then written to any ter- 
minal spawned or respawned from the /etc/inittab file. 

FILES 

/etc/issue 

SEE ALSO 

login(l). 
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NAME 

iwmap — format of iwprep(l) character map description files 

SYNOPSIS 

/usr/lib/f ont/device/MAP.* 

DESCRIPTION 

A map file specifies a character code for a t rof f character name. 
A complete list of the trof f character names may be found in 
the "nrof f /trof f Reference" in A/UX Text Processing Tools. 

Each map file line has the synopsis: 

code charname. . . 

where code and charname are described as follows: 

code Any valid C eight-bit integer constant, including de- 

cimal, octal, and hexadecimal forms. 

charname A one or two character name. One character names 
are used to specify standard ASCII characters (e.g., a, 
b, c, 1, 2, 3). Two character names are used to specify 
special characters. There are two forms of the special 
character names in trof f input The first is a simple 
two character name (e.g., \-, \ I). The second is a 
four character name (e.g., \ (*A, \ (dg). For the two 
character name of special characters, you specify the 
entire name (i.e., \- for \-). For the four character 
name of special characters, you specify just the last 
two characters (i.e., dg for \ (dg). 

EXAMPLES 

An example map file for specifying the code for a dash, hyphen, 
and long dash to the same character is: 

055 - hy - 

Examine the map files in /usr/lib/f ont/deviw for further 
examples. 

FILES 

/usr/lib/f ont/deviw 

SEE ALSO 

iwprep(l). 
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NAME 

linenum- 



line number entries in a common object file 



SYNOPSIS 

finclude <linenum.h> 

DESCRIPTION 

The C compiler generates an entry in the object file for each C 
source line on which a breakpoint is possible (when invoked with 
the -g option; see cc(l)). Users can then reference line numbers 
when using the appropriate software test system (see sdb(l)). 
The structure of these line number entries appears below. 

struct lineno 
{ 

union 



{ 



} 



long 
long 



unsigned short 



l_symndx ; 
l_paddr ; 
l_addr ; 
1 lnno ; 



} ; 



Numbering starts with one for each function. The initial line 
number entry for a function has l_lnno equal to zero, and the 
symbol table index of the function's entry is in l_symndx. Oth- 
erwise, l_lnno is non-zero, and l_paddr is the physical ad- 
dress of the code for the referenced line. Thus the overall struc- 
ture is the following: 



1 addr 



1 lnno 



function symtab index 
physical address line 

physical address line 



function symtab index 
physical address line 

physical address line 



February, 1990 

Revision C 



linenum(4) linenum(4) 



SEE ALSO 

cc(l), sdb(l), a . out(4). 
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NAME 

magic — magic number file for file command 

DESCRIPTION 

The file(l) command identifies the type of a file by using, 
among other tests, a test to ascertain whether the file begins with a 
certain magic number. The file /etc /magic specifies the magic 
numbers are to be tested for, what message to print if a particular 
magic number is found, and what additional information is to be 
extract from the file. 

Each line of the file specifies a test to be performed. A test com- 
pares the data starting at a particular offset in the file with a 1- 
byte, 2-byte, or 4-byte numeric value or a string. If the test 
succeeds, a message is printed. A line consists of the following 
fields: 

offset A number specifying the offset, in bytes, into the file 

of the data which is to be tested. 

type The type of the data to be tested. The possible 

values are 

byte A one-byte value. 

short A two-byte value. 

long A four-byte value. 

string A string of bytes. 

The types byte, short, and long may optionally 
be followed by a mask specifier of the form 
& number. If a mask specifier is given, the value is 
AND'ed with the number before any comparisons 
are done. The number is specified in C form; for ex- 
ample, 13 is decimal, 013 is octal, and 0x13 is 
hexadecimal. 

test The value to be compared with the value from the 

file. If the type is numeric, this value is specified in 
C form; if the type is a string, it is specified as a C 
string with the usual escapes permitted (for example, 
\n fornewline). 

Numeric values may be preceded by a character in- 
dicating the operation to be performed. The charac- 
ter may be an =, to specify that the value from the 
file must equal the specified value, a <, to specify 
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that the value from the file must be less than the 
specified value, a >, to specify that the value from 
the file must be greater than the specified value, or 
an x to specify that any value will match. If the 
character is omitted, it is assumed to be =. 

For string values, the byte string from the file must 
match the specified byte string; the byte string from 
the file which is matched is the same length as the 
specified byte string. 

message The message to be printed if the comparison 
succeeds. If the string contains a print f(3S) for- 
mat specification, the value from the file (with any 
specified masking performed) is printed using the 
message as the format string. 

Some file formats contain additional information which is to be 
printed along with the file type. A line which begins with the 
character > indicates additional that tests and messages are to be 
printed. If the test on the line preceding the first line with a > 
succeeds, the tests specified in all the subsequent lines beginning 
with > are performed, and the messages are printed if the tests 
succeed. The next line which does not begin with a > terminates 
this command. 

FILES 

/etc/magic 

SEE ALSO 

file(l). 

BUGS 

There should be more than one level of subtests, with the level in- 
dicated by the number of > at the beginning of the line. 
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NAME 

master — master kernel configuration files 

DESCRIPTION 

Master files are used by autoconf ig(lM) to obtain device in- 
formation that is necessary to configure new kernels. Master files 
are located in /et c /master, d. 

Master files can contain up to three order-dependent lines of infor- 
mation: a device identifier, a dependency statement, and a device 
specification. The device-identifier and dependency-statement 
lines are optional and precede the device specification, as shown 
below: 

device-identifier 

dependency-statement 

device-specification 

Device Identifier 

The device identifier provides optional information that is useful 
only for slot device drivers. Each slot card stores a board ID 
number and a version number in its ROM. The device identifier is 
used to specify a particular slot card and, optionally, a range of 
version numbers, as shown below: 

id board-id serial 

where board-id is an integer value that matches the board ID that 
is stored in a slot card's ROM. For example, board-id with a 
value of 8 indicates the EtherTalk™ card. The placeholder serial 
is an optional number or number range. If present, serial is com- 
pared with the slot card's version number. If the comparison fails, 
autoconfig terminates. The placeholder serial can be 
specified as: 

number 

The slot card's version number must match number. 

number- 

The slot card's version number must be less than or equal to 
number. 

-number 

The slot card's version number must be greater than or equal 
to number. 

numberl-numberl 

The slot card's version number must be within the range 
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specified by numberl-number2. 

If serial is not specified, autoconf ig does not check the slot 
card's version number. 

Dependency Statements 

Dependency statements can be used to specify modules that must 
be included or excluded in the resulting kernel for proper opera- 
tion of the subject driver. Dependency statements can have 
several forms, from simple to complex: 

verb namelist 

LI filename verb namelist 

if expression verb namelist 

The possible values for verb, namelist, filename, and expression 
are described below: 

verb 

The keyword include or exclude, include tells 
autoconf ig to include the modules specified in namelist 
in the resulting kernel, exclude tells autoconf ig to ex- 
clude the modules specified in namelist from the resulting 
kernel. 

namelist 

A comma-separated list of module names. 

filename 

The name of another master file in the current directory or a 
period (.), which indicates the current master file. If 
filename exists, the modules specified in namelist are includ- 
ed in the resulting kernel. If filename does not exist, the 
modules specified in namelist are excluded. 

expression 

An expression constructed from filenames and operators. If 
the evaluation of the expression is TRUE, the modules 
specified in namelist are included in the resulting kernel. If 
the evaluation of the expression is FALSE, the modules 
specified in namelist are excluded. The following operators, 
listed from highest to lowest priority, can be used to construct 
expression: 

! NOT 

& AND 

| OR 
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Parentheses can be used to override the default priority. The 
following examples use parentheses to demonstrate the de- 
fault priority of the operators: 

a | b & c is equivalent to a | (b & c) 
! a & b is equivalent to ( ! a) & b 

Device Specification 

The device specification provides information that autoconf ig 
must know to produce a complete and working kernel. A device 
specification is comprised of the following six fields: 

flags 

vectors 

prefix 

major-number 

maximum-devices 

interrupt-level 

The fields must appear on a single line in the master file in the 
order shown above and must be separated by one or more blanks 
or tabs. Each field is described below: 

flags 

One or more of the following characters: 

a Tell autoconf ig to create prefixcnt and 
prefixaddr data structures for this module. The 
value of prefix is discussed below. 

b Tell autoconf ig to create a bdev switch entry 
for this module. 

c Tell autoconf ig to create a cdev switch entry 
for this module. 

1 Tell autoconf ig to create a line discipline switch 
entry for this module. 

m Tell autoconf ig to create a Streams entry for 
this module. 

n Tell autoconf ig that this module uses a network 
interface (TCP/IP). 

popt 

Tell autoconf ig that this module has an initiali- 
zation routine, autoconf ig generates code that 
calls the initialization routine at the point in the dur- 
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ing system boot specified by opt, which can be any 
of the following characters: 

f Call this module's initialization routine 
first, before any other initialization occurs. 
Interrupts are disabled. 

s Call this module's initialization routine 
after any pf modules. Interrupts are dis- 
abled. 

n Call this module's initialization routine 
after any pf and ps modules but prior to 
enabling interrupts. If popt is not 
specified, n is the default. 

Call this module's initialization routine 
after enabling interrupts. 

1 Call this module's initialization routine be- 
fore entering /etc/init. 

s Tell autoconf ig that this module is a software 
module that does not drive a hardware device. Of 
the other possible values for flags, only the p flag 
can be used with the s flag. 

t Tell autoconf ig that this module is a character 
device driver that requires a tty structure. The t 
flag must be used with the c flag. 

wopt 

Tell autoconf ig to link this driver to the inter- 
rupt vector mechanism. Currently, the only valid 
value of opt is s, which tells the kernel to decode 
slot-based interrupts and call the interrupt routine of 
this driver when the card generates an interrupt. 

x Tell autoconf ig that this module is a Streams 
module. Only the p flag can be used with the x 
flag. 

Sopt 

Specify opt as one of the following characters: 

e Tell autoconf ig that this module con- 
tains a special exit routine. 
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f Tell autoconf ig that this module con- 
tains a special fork routine. 

x Tell autoconf ig that this module con- 
tains a special exec routine. 

vectors 

The number of interrupt vectors that a particular controller 
can generate. For hardware device drivers, this value must be 
a nonzero integer. For drivers that receive slot interrupts, this 
number is 1 because each controller can generate only one in- 
terrupt For software modules, that do not drive a hardware 
device this value should be a hyphen (-). 

prefix 

The prefix used in the driver's open, close, read, write, ioctl, 
print, select, and strategy routines. For example, if the 
driver's open routine is called bddopen, the prefix is bdd. 
The placeholder prefix must be between three and eight char- 
acters long. Valid characters are alphanumerics and the 
underline (_) character. To maintain consistency, prefix 
should also be the name of the master file. 

major-number 

The value that is assigned as the major number for the device 
driver. This value should always be a hyphen (-). When a 
hyphen is specified in this field, autoconf ig assigns the 
first available major number to the device. Letting auto- 
conf ig assign the major number guarantees a unique major 
number for each device driver and prevents conflict between 
two or more device drivers. 

maximum-devices 

Either a hyphen (-) for software modules or a nonzero integer 
for hardware device drivers. The integer value is the number 
of devices the controller supports. 

interrupt-level 

The highest-priority interrupt level used by the controller. 
For software modules, this value should be a hyphen (-). For 
slot-based devices, all of which interrupt at spll, this value 
should be 1. 
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EXAMPLES 

The following master file is for a block device driver: 

if . include SCSI 

bca - bdd 2 1 

The if . include SCSI statement forces the inclusion of 
another module, SCSI (the SCSI Manager), on which this device 
depends. The b and c flags indicate that the driver is used as 
both a block and a character device driver, so autoconf ig will 
create entries for this device in both the bdevsw and cdevsw 
tables. The a flag tells autoconfig to create the bddcnt 
and bddaddr data structures. 

Because this device receives interrupts via the SCSI Manager, the 
hyphen (-) in the second field is used to tell autoconfig that 
this device does not receive interrupts directly. The device's 
prefix is bdd, and, because the fourth field contains a hyphen, 
autoconfig assigns the device driver's major number. 

The 2 in the fifth field indicates that there are two devices per 
controller, and the 1 in the sixth field indicates that the device's 
interrupt level is spll. 

FILES 

/ etc /ma st e r . d Default location of master files 

SEE ALSO 

autoconf ig(lM). 

Building A/UX Device Drivers, which is available from APDA™. 
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NAME 

mtab — mounted file system table 

DESCRIPTION 

mtab resides in directory /etc and contains a record of all file 
systems mounted on this machine. Whenever a mount is done, 
an entry is made in the mtab file, umount removes entries. The 
table is a series of lines with form identical to that of 
/etc/fstab. 

FILES 

/etc /mtab 

SEE ALSO 

mount(lM), shutdown(lM), umount(lM), fstab(4). 
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NAME 

NETADDRS — network address database 

DESCRIPTION 

The NETADDRS file resides in /etc and contains information re- 
garding the network addresses of each EtherTalk board on the lo- 
cal machine. For each board, a single line should be present with 
the following items of information: 

unit-number internet-address broadcast-address netmask 

Items are separated by any number of blanks and/or tab charac- 
ters. Lines must not begin with blanks or tabs, netmask should be 
blank if subnets are not being supported. 

EXAMPLES 

The following is a sample NETADDRS file for a machine on two 
networks; only the second is subnetted. 

89.53 89.0 

1 91.1.0.48 91.1.0.0 255.255.0.0 

FILES 

/etc/NETADDRS 

SEE ALSO 

autoconf ig(lM), if conf ig(lM). 
AIUX Network System Administration 

RFC-917, RFC-922, RFC-944, RFC-950 (DDN Network Informa- 
tion Center , SRI International) 
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NAME 

netgroup — list of network groups 

DESCRIPTION 

netgroup defines network-wide groups, which are used for per- 
mission checking when doing remote mounts, remote logins, and 
remote shells. Each line of the netgroup file defines a group 
and has the format 

groupname member 1 member! . . . 

where memberl is either another group name or a triple of the 
form 

(hostname, user name, domainname) 

Any of three fields can be empty, in which case it signifies a wild 
card. Thus 

universal (, , ) 

defines a group to which everyone belongs. 

Network groups are accessed through the yellow pages. The data- 
base actually used by the yellow pages are in the two files 

/etc/yp /domainname/ netg. dir 
I etc /yp/ domainname /netg . pag 

These files can be created from /etc/netgroup using 
makedbm(lM). 

FILES 

/etc/netgroup 

/etc/yp I domainname /netg. dir 

/etc/yp/ domainname /netp.pag 

SEE ALSO 

makedbm(lM), ypserv(lM), getnetgrent(3), 
exports(4). 
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NAME 

networks — network name database 

DESCRIPTION 

The networks file contains information regarding the known 
networks which comprise the DARPA Internet. For each network 
a single line should be present with the following information: 

official network name 
network number 
aliases 

Items are separated by any number of blanks and/or tab charac- 
ters. A *'#" indicates the beginning of a comment; characters up 
to the end of the line are not interpreted by routines which search 
the file. This file is normally created from the official network 
data base maintained at the Network Information Control Center 
(NIC), though local changes may be required to bring it up to date 
regarding unofficial aliases and/or unknown networks. 

Network number may be specified in the conventional "." nota- 
tion using the inet_networkO routine from the Internet ad- 
dress manipulation library, inet(3N). Network names may con- 
tain any printable character other than a field delimiter, newline, 
or comment character. 

FILES 

/etc/networks 

SEE ALSO 

getnetent(3N). 

BUGS 

A name server should be used instead of a static file. A binary in- 
dexed file format should be available for fast access. 
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NAME 

passwd — password file 

SYNOPSIS 

/etc/passwd 

DESCRIPTION 

The passwd file contains for each user the following informa- 
tion: 

name User's login name; contains no uppercase characters 

and must not be greater than eight characters long. 

password encrypted password as well as aging information 

numeric-user-ID 

This is the user's ID in the system and it must be 
unique. 

numeric-group-ID 

This is the number of the group that the user belongs 
to. 

real-name In some versions of UNIX, this field also contains the 
user's office, extension, home phone, and so on. For 
historical reasons this field is called the GCOS field. 

default-working-directory 

The directory that the user is positioned in when they 
log in — this is known as the 'home' directory. 

shell program to use as Shell when the user logs in. 

The user's real name field may contain "&", meaning insert the 
login name. 

The password file is an ASCII file. Each field within each user's 
entry is separated from the next by a colon. Each user is separated 
from the next by a newline. If the password field is null, no pass- 
word is demanded; if the shell field is null, /bin/sh is used. 

This file resides in directory /etc. Because of the encrypted 
passwords, it can and does have general read permission and can 
be used, for example, to map numeric user ID to names. 

The encrypted password consists of 13 characters chosen from a 
64-character alphabet (. , /, 0-9, A-z, a-z), except when the 
password is null, in which case the encrypted password is also 
null. Password aging is effected for a particular user if his en- 
crypted password in the password file is followed by a comma and 
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a non-null string of characters from the above alphabet. (Such a 
string must be introduced in the first instance by the superuser.) 

The first character of the age, M say, denotes the maximum 
number of weeks for which a password is valid. A user who at- 
tempts to login after his password has expired will be forced to 
supply a new one. The next character, m say, denotes the 
minimum period in weeks which must expire before the password 
may be changed. The remaining characters define the week 
(counted from the beginning of 1970) when the password was last 
changed. (A null string is equivalent to zero.) M and m have nu- 
merical values in the range 0-63 that correspond to the 64- 
character alphabet shown above (i.e., / = 1 week; z = 63 weeks). 
If m = M = (derived from the string . or . . ) the user will be 
forced to change his password the next time he logs in (and the 
"age" will disappear from his entry in the password file). If m > 
M (signified, e.g., by the string . /) only the superuser will be able 
to change the password. 

The passwd file can also have line beginning with a plus (+), 
which means to incorporate entries from the yellow pages. There 
are three styles of + entries: all by itself, + means to insert the en- 
tire contents of the yellow pages password file at that point; 
+name means to insert the entry (if any) for name from the yellow 
pages at that point; +Qname means to insert the entries for all 
members of the network group name at that point If a + entry has 
a nonnull password, directory, GCOS, or shell field, they will 
overide what is contained in the yellow pages. The numeric user 
ID and group ID fields cannot be overridden. 

EXAMPLES 

Here is a sample /etc /passwd file: 

root : q. mJzTnu8icF . : : 10 : God: / : /bin/csh 

ja: 6k/7KCFRPNVXg: 508 :10 : Jerry Asher : /usr2/ ja: /bin/csh 

+melissa: 

+@documentation: no-login: 

+: : : Guest 

In this example, there are specific entries for users root and ja, 
in case the yellow pages are out of order. The user me 1 i s s a will 
have her password entry in the yellow pages incorporated without 
change; anyone in the netgroup documentation will have their 
password field disabled, and anyone else will be able to log in 
with their usual password, shell, and home directory, but with a 
GCOS field of Guest. 
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Appropriate precautions must be taken to lock the 
/etc/passwd file against simultaneous changes if it is to be 
edited with a text editor, vipw does the necessary locking. 

FILES 

/etc/passwd 

SEE ALSO 

login(l), passwd(l), vipw(lM), crypt(3), getpwent(3), 
group(4). 
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NAME 

phones — remote host telephone number database 

DESCRIPTION 

The file /etc /phones contains the system-wide private tele- 
phone numbers for the tip(lC) program. This file is normally 
unreadable and may contain privileged information. The format 
of the file is a series of lines of the form 

system-name [ \t ] * phone-number 

The system name is one of those defined in the remote(4) file 
and the telephone number is constructed from any sequence of 
characters terminated only by a comma (, ) or the end of the line. 
The = and * characters are indicators that inform the auto-call un- 
its to pause and wait for a second dial tone (when going through 
an exchange). The = is required by the DF02-AC and the * is re- 
quired by the BIZCOMP 1030. 

Only one telephone number per line is permitted. However, if 
more than one line in the file contains the same system name, 
tip(lC) will attempt to dial each one in turn, until it establishes a 
connection. 

EXAMPLES 

As distributed, the file /etc/phones contains a dummy entry. 
This should be replaced by a line (or lines) in the format described 
earlier. For example, 

plato *5551234, 
hegel *5551235, 

FILES 

/etc/phones 

SEE ALSO 

tip(lC), remote(4). 
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NAME 

plot — graphics interface 

DESCRIPTION 

Files of this format are produced by routines described in 
plot(3X) and are interpreted for various devices by commands 
described in tplot(lG). A graphics file is a stream of plotting 
instructions. Each instruction consists of an ASCII letter usually 
followed by bytes of binary information. The instructions are exe- 
cuted in order. A point is designated by four bytes representing 
the x and y values; each value is a signed integer. The last desig- 
nated point in an 1, m, n, or p instruction becomes the 
"current point" for the next instruction. 

Each of the following descriptions begins with the name of the 
corresponding routine in plot(3X). 

m move: The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by 
the next four bytes. See tplot(lG). 

p point Plot the point given by the next four bytes. 

1 line: Draw a line from the point given by the next four bytes 
to the point given by the following four bytes. 

t label: Place the following ASCII string so that its first charac- 
ter falls on the current point. The string is terminated by a 
newline. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a newline, as the 
style for drawing further lines. The styles are "dotted", 
"solid", "longdashed", "shortdashed", and "dotdashed". 
Effective only for the -T4 014 and -Tver options of 
tplot(lG) (TEKTRONIX 4014 terminal and Versatec 
plotter). 

s space: The next four bytes give the lower left corner of the 
plotting area; the following four give the upper right corner. 
The plot will be magnified or reduced to fit the device as 
closely as possible. 

Space settings that exactly fill the plotting area with unity scaling 
appear below for devices supported by the filters of tplot(lG). 
The upper limit is just outside the plotting area. In every case the 
plotting area is taken to be square; points outside may be display- 
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able on devices whose face is not square. 



DASI 300 
DASI 300s 
DASI 450 
TEKTRONIX 4014 
Versatec plotter 



space(0, 0,4096, 4096) 
space(0, 0,4096, 4096) 
space(0, 0,4096, 4096) 
space(0, 0, 3120, 3120) 
space(0, 0, 2048, 2048) 



SEE ALSO 

tplot(lG), plot(3X), term(4). 

WARNINGS 

The plotting library plot(3X) and the curses library 
curses(3X) both use the names erase ( ) and move ( ) . The 
curses versions are macros. If you need both libraries, put the 
plot(3X) code in a different source file than the curses(3X) 
code, and/or #undef move ( ) and erase ( ) in the plot(3X) 
code. 
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NAME 

postscript — PostScript print file format 

DESCRIPTION 

The PostScript print file format is a programming language with 
powerful graphics primitives for describing printed pages. A 
growing number of devices which print PostScript page descrip- 
tions are available. PostScript printer include the Apple Laser- 
Writer®, QMS PS-800, 1200, and 2400, Dataproducts LZR-2665 
and 2660, and Linotype Linotronic 100 and 300 typesetters. The 
TranScript package of UNIX software allows UNIX systems ac- 
cess to PostScript printers. 

The complete PostScript language is described in the book 

PostScript Language Reference Manual 

by Adobe Systems Incorporated 

published by Addison- Wesley Publishing Company 

ISBN 0-201-10174-2, 322 pages, illustrated 

Library of Congress: QA76.73.P67P67 1985 005. 13 '3 

85-15693 

The Reference Manual provides a comprehensive presentation of 
of the language, its graphics, and its font facilities, including the 
precise semantics of every PostScript operator. Also covered 
are a set of PostScript file structuring conventions which are 
used by the TranScript system components. 

SEE ALSO 

transcript(lM). 
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NAME 

printcap — printer-capability database 

SYNOPSIS 

/etc/printcap 

DESCRIPTION 

printcap is a simplified version of the termcap(4) database 
used to describe line printers. The spooling system accesses the 
printcap file every time it is used, allowing dynamic addition 
and deletion of printers. Each entry in the database is used to 
describe one printer. This database may not be substituted, as is 
possible for termcap, because it may allow accounting to be 
bypassed. 

The default printer is normally lp, though the environment vari- 
able PRINTER may be used to override this. Each spooling utility 
supports the flag option -Pprinter to allow explicit naming of a 
destination printer. 

For a complete discussion on how setup the database for a given 
printer see A/UX Local System Administration.. 

CAPABILITIES 

Refer to termcap(4) for a description of the file layout 

Description 

Name of accounting file. 

If lp is a tty, set the baud rate (ioctl call). 

If lp is a tty, clear control flag bits (termio . h). 

ci f pi ot data filter. 

Similar to cc, but set the bits. 

Tex data filter (DVI format). 

If 1 p is a tty, use DTR/DCD flow control. 

String to send for a form feed. 

Print a form feed when device is opened. 

Graph data filter (pi ot(3X) format). 

Print the burst header page last 

If lp is a tty, clear input flag bits (t e r mi o . h ) . 

Name of text filter that does accounting. 

Similar to i c, but set the bits. 

If 1 p is a tty, clear the local flag bits (t e rmi o . h). 

Error logging filename. 

Name of lock file. 

Device name to be opened for output. 

Similar to 1 c, but set the bits. 



Name Type 


Default 


af 


str 


NULL 


br 


num 


none 


cc 


num 





cf 


str 


NULL 


cs 


num 





df 


str 


NULL 


fd 


bool 


FALSE 


ff 


str 


•*\p ' 


fo 


bool 


FALSE 


gf 


str 


NULL 


hi 


bool 


FALSE 


ic 


num 





if 


str 


NULL 


is 


num 





lc 


num 





If 


str 


"/dev/console" 


lo 


str 


"lock" 


IP 


str 


"/dev/printer" 


Is 


num 
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Maximum file size (in BUFSIZ blocks). Use for unlimited size. 
Next directory for list of queues (unimplemented). 
Ditroff data filter (device independent troff). 
If lp is a try, clear output flag bits (termi o . h). 
Name of the output filtering program. 
Similar to oc but set the bits. 
Price per foot or page in hundredths of a cent. 
Page length (in lines). 
Page width (in characters). 
Page width in pixels (horizontal). 
Page length in pixels (vertical). 
Filter for printing FoRTRAN-style text files. 
Restricted group. Only members of the group are allowed access. 
Machine name for remote printer. 
Remote printer-name argument 
Restrict remote users to those with local accounts. 
Open the printer device for reading and writing. 
Short banner (one line only). 
Suppress multiple copies. 
1** Spool directory. 
Suppress form feeds. 
Suppress printing of burst page header. 
Status filename. 

Troff data filter (cat phototypesetter). 
Trailer string to print when queue empties. 
Raster image filter. 

If the local line-printer driver supports indentation, the daemon 
must understand how to invoke it 

FILTERS 

The lpd(8) daemon creates a pipeline of filters to process files for 
various printer types. The filters selected depend on the flags 
passed to lpr(l). The pipeline set up is: 



mx 


num 


1000 


nd 


str 


NULL 


nf 


str 


NULL 


oc 


num 





of 


str 


NULL 


OS 


num 





pc 


num 


200 


pi 


num 


66 


pw 


num 


132 


px 


num 





py 


num 





rf 


str 


NULL 


rg 


str 


NULL 


rm 


str 


NULL 


rp 


str 


'V' 


rs 


bool 


FALSE 


rw 


bool 


FALSE 


sb 


bool 


FALSE 


sc 


bool 


FALSE 


sd 


str 


"/usr/spo 


sf 


bool 


FALSE 


sh 


bool 


FALSE 


St 


str 


"status" 


tf 


str 


NULL 


tr 


str 


NULL 


vf 


str 


NULL 



"P 


pr | if 


Regular text + pr(l) 


none 


if 


Regular text 


-c 


cf 


cifplot 


-d 


df 


CVI (tex) 


-g 


gf 


plot (3) 


-n 


nf 


ditroff 


-f 


rf 


Fortran 


-t 


tf 


troff 


— V 


vf 


Raster image 



February, 1990 

Revision C 



printcap(4) printcap(4) 



The if filter is invoked with arguments: 

if [ -c ] -wwidth -llength -Undent -n login -h 
host acct-file 

The -c flag option is passed only if the -1 flag option (pass con- 
trol characters literally) is specified to lpr. The values of width 
and length specify the page width and length (from pw and pi, 
respectively) in characters. The -n and -h parameters specify the 
login name and the host name of the owner of the job, respective- 
ly. The value of acct-file is passed from the af printcap entry. 

If no if filter is specified, the of filter is used instead, with the 
distinction that of is opened only once, while if is opened for 
every individual job. Thus, if is better suited to performing ac- 
counting. The of filter only has the width and length flag options. 

All other filters are called as follows: 

filter -xwidth -y length -n login -h host acct-file 

where width and length are represented in pixels, specified by the 
px and py entries, respectively. 

All filters take stdin as the file and stdout as the printer, may 
log either to stderr or syslog(3), and must not ignore SIGINT. 

ERRORS 

Error messages generated by the line printer programs themselves 
(the lp* programs) are logged by syslog(3) using the LPR fa- 
cility. Messages printed on stderr of one of the filters are sent 
to the corresponding If file. The filters may, of course, use sys- 
log themselves. 

Error messages sent to the console have both a Return and a line 
feed appended to them, rather than just a line feed. 

SEE ALSO 

termcap(4), lpc(lm), lpd(lm), pac(lm), lpr(l), lpq(l), 
lprm(l). 



February, 1990 

Revision C 



profile(4) profile(4) 



NAME 

profile — setting up an environment at login time 

DESCRIPTION 

If your login directory contains a file named . profile, that file 
will be executed (via the shell's exec .profile) before your 
session begins; .profiles are handy for setting exported en- 
vironment variables and terminal modes. If the file 
/etc /profile exists, it will be executed for every user before 
the . profile. The following example is typical. 

trap ""123 

TZ=Vbin/cat /etc/TIMEZONE * 

PATH=/usr/lib/acct : /bin : /usr/bin 

TERM=mac2 

MAILCHECK=60 

MAILPATH=/usr/mail/$LOGNAME 

export LOGNAME TZ TERM PATH 

readonly LOGNAME 

umask. 022 

case "$0" in 

-sh | -rsh) 

trap : 1 2 3 

cat /etc/motd 

trap "" 1 2 3 

if mail -e 

then 

echo "you have mail" 

fi 

if [ $LOGNAME != root ] 



then 
fi 



news -n 



-su) 



esac 

trap 12 3 

stty susp ' "Z r 

stty erase DEL intr '~C 

stty ixon 

FILES 

/etc/profile 
$HOME/. profile 
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SEE ALSO 

env(l), login(l), mail(l), sh(l), stty(l), su(l), en- 
viron(5), term(5). 
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NAME 

protocols — protocol name database 

DESCRIPTION 

The protocols file contains information regarding the known 
protocols used in the DARPA Internet. For each protocol a single 
line should be present with the following information: 

official protocol name 
protocol number 
aliases 

Items are separated by any number of blanks or tab characters. A 
# indicates the beginning of a comment; characters up to the end 
of the line are not interpreted by routines which search the file. 

Protocol names may contain any printable character other than a 
field delimiter, newline, or comment character. 

FILES 

/etc/protocols 

SEE ALSO 

getprotoent(3N). 

BUGS 

A name server should be used instead of a static file. A binary in- 
dexed file format should be available for fast access. 
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NAME 

ptab — partition table file 

SYNOPSIS 

/etc/ptab 

DESCRIPTION 

The ptab file contains information regarding the known parti- 
tions present on the local machine. It is read and/or modified by 
the pname(lM) utility. The system administrator can modify it 
with a text editor, though this is not recommended. 

For each partition a single line should be present with the follow- 
ing information: 

name Name of the partition — must not be greater than 32 

characters long. 

type Type of the partition — must not be greater than 32 

characters long. If this field is left empty, the default 
type Apple_UNlx_SVR2 will be assumed. 

controller This is the controller number of the disk containing 
this partition. 

disk This is the disk number (for the specified controller) 

of the disk containing this partition. 

slice This is the slice (partition) number of the partition. 

comment All additional information at the end of the line is 
treated as a comment. 

The partition table file is an ASCII file. Fields within an entry are 
separated from eachother by colons. Each entry is separated from 
the next by a newline. Entries are separated by newlines. The 
ptab file can also have a line beginning with the sharp character 
(#), which means that this line should be treated as a comment and 
ignored. 

EXAMPLES 

Here is a sample /etc/ptab file: 

♦name : type : controller : disk : slice [ : comment ] 

#root : :0:0:0:assigned by default 

tswap: :0:0:l:as signed by default 

src: :0:0:3 

users: :1 :0:0:on extra disk 

Macintosh: Apple HFS: 0: 0: 13:Mac partition 
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FILES 

/etc/ptab 

SEE ALSO 

dp(lM), pname(lM), getptabent(3). 

WARNINGS 

Appropriate precautions must be taken to lock the /etc/ptab 
file against simultaneous modifications. 

BUGS 

The current revision of the software will not support colons ( : ) in 
partition names or partition types. 
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NAME 

res file — format of an RCS file 

DESCRIPTION 

An RCS file is an ASCII file. Its content is described by the gram- 
mar below. The text is free format; that is, spaces, tabs, and new- 
lines have no significance except in strings. Strings are enclosed 
by @ . If a string contains an @ , it must be doubled. 

The metasyntax uses the following conventions: I (bar) separates 
alternatives; { and } enclose optional phrases; { and }* enclose 
phrases that may be repeated zero or more times; { and }+ enclose 
phrases that must appear at least once and may be repeated; non- 
terminal symbols are set in italic font, and literals are set in a 
constant-width font. 



rcstext 



admin {delta}* desc {deltatext}* 



admin 


::= 


head 


{num}; 






access 


{id}*', 






symbols 


{id: num}*; 






locks 


{id: num}*; 






comment 


{string}; 


delta 


::= 


num 








date 


num; 






author 


id; 






state 


{id}; 






branches 


{num}*; 






next 


{num}; 


desc 


::= 


desc 


string 


deltatext 


i'. = 


num 








log 


string 






text 


string 


num 


::= 


[<*&{•))+ 




digit 


::= 


1 1 1 ... 1 9 




id 


::= 


letter {idchar}* 




letter 


::= 


A 1 B 1 ... 1 Z 1 a 


lbl...lz 
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idchar ::= Any printing ASCII character except space, 

tab, carriage return, newline, and special. 

special ::- ; I : I f I @ 

string ::= @ {any ASCII character, with @ doubled} *@ 

Identifiers are case sensitive. Keywords are in lowercase only. 
The sets of keywords and identifiers may overlap. 

The delta nodes form a tree. All nodes whose numbers consist of 
a single pair (2.3, 2.1, 1.3, and so forth) are on the trunk and are 
linked through the next field in order of decreasing numbers. The 
head field in the admin node points to the head of that sequence 
which contains the highest pair. 

All delta nodes whose numbers consist of 2n fields (n>2) (3.1.1.1, 
2.1.2.2, and so forth) are linked as follows. All nodes whose first 
(2n)-l number fields are identical are linked through the next field 
in order of increasing numbers. For each such sequence, the delta 
node whose number is identical to the first 2(n-l) number fields of 
the deltas on that sequence is called the branchpoint. The 
branches field of a node contains a list of the numbers of the first 
nodes of all sequences for which it is a branchpoint This list is 
ordered in increasing numbers. 

DISCLAIMER 

This reference manual entry describes a utility that Apple under- 
stands to have been released into the public domain by its author 
or authors. Apple has included this public domain utility for your 
convenience. Use it at your own discretion. Often the source 
code can be obtained if additional requirements are met, such as 
the purchase of a site license from an author or institution. 

IDENTIFICATION 

Author: Walter F. Tichy, Purdue University, West Lafayette, IN 

47907. 

Copyright © 1982 by Walter F. Tichy. 

SEE ALSO 

ci(l), co(l), ident(l), rcs(l), rcsdif f (1), rcsintro(l), 
rcsmerge(l), rlog(l), sccstorcs(lM). 
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NAME 

reloc — relocation information for a common object file 

SYNOPSIS 

♦include <reloc.h> 

DESCRIPTION 

Object files have one relocation entry for each relocatable refer- 
ence in the text or data. If relocation information is present, it will 
be in the following format 

struct reloc 

{ 

long r_vaddr ; /* (virtual) address of 

reference */ 

long r_symndx ; /* index into symbol table */ 

short r_type ; /* relocation type */ 

} ; 



/* 

* All generics 

* reloc already performed to symbol in the 

* same section 
*/ 

# define R_ABS 

/* 

* DEC Processors VAX 11/780 and VAX 11/750 

* 

*/ 

#define R_RELBYTE 017 

# define R_RELWORD 020 

#define R_RELLONG 021 

#define R_PCRBYTE 022 

# define R_PCRWORD 023 

# define R_PCRLONG 024 

/* 

* Motorola 68000 uses R_RELBYTE, R_RELWORD, R_RELLONG, 

* R_PCRBYTE, and R_PCRWORD as for DEC machines above. 
*/ 

As the link editor reads each input section and performs reloca- 
tion, the relocation entries are read. They direct how references 
found within the input section are treated. 

r_abs The reference is absolute, and no relocation is 

necessary. The entry will be ignored. 
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R_relbyte A direct 8-bit reference to a symbol's virtual 
address. 

r_relword A direct 16-bit reference to a symbol's virtual 
address. 

r_rellong A direct 32-bit reference to a symbol's virtual 
address. 

R_PCRBYTE A "PC-relative" 8-bit reference to a symbol's 
virtual address. 

R_PCRWORD A "PC-relative" 16-bit reference to a symbol's 
virtual address. 

R_PCRLONG A "PC-relative" 32-bit reference to a symbol's 
virtual address. 

On the VAX processors, relocation of a symbol index of -1 indi- 
cates that the relative difference between the current segment's 
start address and the program's load address is added to the relo- 
catable address. 

Other relocation types will be denned as they are needed. 

Relocation entries are generated automatically by the assembler 
and automatically utilized by the link editor. A link editor option 
exists for removing the relocation entries from an object file. 

SEE ALSO 

ld(l), strip(l), a . out(4), syms(4). 
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NAME 

remote — remote host description file 

SYNOPSIS 

/etc/remote 

DESCRIPTION 

The systems known by tip(lC) and their attributes are stored in 
an ASCII file which is structured somewhat like the termcap(4) 
file. Each line in the file provides a description for a single sys- 
tem. Fields are separated by a colon ( : ). Lines ending in a \ 
character with a newline immediately following are continued on 
the next line. 

The first entry is the name(s) of the host system. If there is more 
than one name for a system, the names are separated by vertical 
bars. Following the name of the system are the fields of the 
description. A field name followed by an = sign indicates that a 
string value follows. A field name followed by a # sign indicates 
a following numeric value. 

Entries named tip* and cu* are used as default entries by tip, 
and the cu interface to tip, as follows: When tip is invoked 
with only a telephone number, it looks for an entry of the form 
tip300, where 300 is the baud rate with which the connection is 
to be made; when the cu interface is used, entries of the form 
cu300 are used. 

CAPABILITIES 

Capabilities are either strings (str), numbers (num), or boolean 
flags (bool). A string capability is specified by capability=value; 
for example, dv=/dev/harris. A numeric capability is 
specified by capability#value\ for example, xa#99. A boolean 
capability is specified by simply listing the capability. 

at (str) Auto call unit type. 

br (man) The baud used in establishing a connection to the 
remote host. This is a decimal number and the default is 
300 baud. 

cm (str) An initial connection message to be sent to the re- 
mote host. For example, if a host is reached through a 
port selector, this might be set to the appropriate se- 
quence required to switch to the host 
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cu (str) Call unit if making a telephone call. Default is the 
same as the dv field. 

di (str) Disconnect message sent to the host when a discon- 
nect is requested by the user. 

du (boot) This host is on a dialup line. 

dv (str) Device(s) to open to establish a connection. If this 
file refers to a terminal line, tip(lQ attempts to perform 
an exclusive open on the device to insure that only one 
user at a time has access to the port. 

el (str) Characters marking an end-of-line. The default is 
NULL. The character ~ escapes are only recognized by 
tip after one of the characters in el, or after a return. 

f s (str) Frame size for transfers. The default frame size is 
equaltoBUFSlz. 

hd (boot) The host uses half-duplex communication; local 
echo should be performed. 

ie (str) Input end-of-file marks. The default is NULL. 

mt (str) Modem type (for use by tip). If mt is specified, 
die at field must appear as at="generic". tip will 
then look in /etc /dialup for the appropriate modem 
escape sequences and call the generic dialup routine. If 
mt is not specified, tip will assume that it was compiled 
with the appropriate modem interface module 

$(CC) -O tip -D${MODEM} 

oe (str) Output end-of-file string. The default is NULL. 
When tip is transferring a file, this string is sent at end- 
of-file. 

pa (str) The type of parity to use when sending data to the 

host. This may be one of even, odd, none, zero (al- 
ways set bit 8 to zero), or one (always set bit 8 to 1). 
The default is even parity. 

pn (str) Telephone number(s) for this host. If the telephone 
number field contains an @ sign, tip searches the 
/etc/phones file for a list of telephone numbers (see 
phones(4)). 

tc (str) Indicates that the list of capabilities is continued in 
the named description. This is used primarily to share 
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common capability information. 

Here is a short example showing the use of the capability con- 
tinuation feature 

UNIX-1200:\ 

:dv=/dev/cua0:el= A D"U A C"S A Q A O@:du:at=ventel:ie=#$%:\ 

:oe= A D:br#1200: 

arpavax I ax : \ 

:pn=7654321%:tc=UNIX-1200 

FILES 

/etc/ remote 

SEE ALSO 

tip(lC), phones(4). 
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NAME 

resolver — re solver configuration file 

SYNOPSIS 

/etc/resolv.conf 

DESCRIPTION 

The resolver configuration file contains information that is 
read by the resolver routines the first time they are invoked by a 
process. The file is designed to be human readable and contains a 
list of name- value pairs that provide various types of resolver in- 
formation. 

On a normally configured system this file should not be necessary. 
The only name server to be queried will be on the local machine 
and the domain name is retrieved from the system. 

The different configuration options are: 

nameserver 

followed by the Internet address (in dot notation) of a name 
server that the resolver should query. At least one name 
server should be listed. Up to MAXNS (currently 3) name 
servers may be listed, in that case the resolver library queries 
tries them in the order listed. If no nameserver entries are 
present, the default is to use the name server on the local 
machine. (The algorithm used is to try a name server, and if 
the query times out, try the next, until out of name servers, 
then repeat trying all the name servers until a maximum 
number of retries are made). 

domain 

followed by a domain name, that is the default domain to ap- 
pend to names that do not have a dot in them. If no domain 
entries are present, the domain returned by 
gethostname(2N) is used (everything after the first ".")• 
Finally, if the host name does not contain a domain part, the 
root domain is assumed. 

The name value pair must appear on a single line, and the key- 
word (e.g. nameserver) must start the line. The value follows the 
keyword, separated by white space. 

FILES 

/etc/resolv. conf 
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SEE ALSO 

named(lM), gethostbyname(3N), resolver(3N). 
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NAME 

r hosts — trusted hosts file format 

DESCRIPTION 

The login directory for each user can contain a . rhosts file that 
enumerates remote hosts having equivalent account names. (The 
hosts names must be the standard names as described in 
remsh(lN)). 

Each line in this file should contain a rhost and a username 
separated by a space, allowing additional cases where logins 
without passwords are to be permitted. 

When you rlogin as the same user on an equivalent host, you 
don't need to give a password. 

To avoid security problems, the . rhosts file must be owned by 
either the remote user or root. Note that, for security reasons, root 
is an exception to the above; a superuser on an equivalent host 
must still supply the password to remotely login as root unless the 
root account has its own private equivalence list in a file 
. rhosts in the root directory. Note that a . rhosts file for the 
root account is not recommended where secure systems are re- 
quired. 

Your remote terminal type is the same as your local terminal type 
(as given in your environment TERM variable). See rlogin(lN) 
for other details concerning the line discipline and escape charac- 
ters. 

FILES 

/home-directory/ . rhosts 

SEE ALSO 

remsh(lN), rlogin(lN). 
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NAME 

rmtab — remotely mounted file system table 

DESCRIPTION 

rmtab resides in directory /etc and contains a record of all 
clients that have done remote mounts of file systems from this 
machine. Whenever a remote mount is done, an entry is made in 
the rmtab file of the machine serving up that file system, 
umount removes entries, umount -a broadcasts to all servers, 
and informs them that they should remove all entries from rmtab 
created by the sender of the broadcast message. By placing a 
umount -a command in /etc/sysinitrc, rmtab tables 
can be purged of entries made by a crashed host, which upon re- 
booting did not remount the same file systems it had before. The 
table is a series of lines of the form 

hostname '.directory 

This table is used only to preserve information between crashes, 
and is read only by mountd(lM) when it starts up. mountd 
keeps an in-core table, which it uses to handle requests from pro- 
grams like showmount(lM) and shutdown(lM). 

FILES 

/etc/rmtab 

SEE ALSO 

mount(lM), mountd(lM), showmount(lM), 
shutdown(lM), umount(lM). 

BUGS 

Although the rmtab table is close to the truth, it is not always 
100% accurate. 
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NAME 

rpc — RPC program number database 

SYNOPSIS 

/etc/rpc 

DESCRIPTION 

The rpc file contains user-readable names that can be used in 
place of RPC program numbers. Each line has the following 
items of information: 

server-name program-number [ alias. . .] 

Items are separated by any number of blanks or tab characters. 
Use # to indicate the beginning of a comment; characters up to the 
end of the line are not interpreted by routines which search the 
file. 



# 

# rpc 

# 

portmapper 


1.1 86/07/07 


100000 


portmap sunrpc 


rstatd 


100001 


rstat rup perfmeter 


rusersd 


100002 


rusers 


nfs 


100003 


nfsprog 


ypserv 


100004 


ypprog 


mountd 


100005 


mount showmount 


ypbind 


100007 




walld 


100008 


rwall shutdown 


yppasswdd 


100009 


yppasswd 


etherstatd 


100010 


etherstat 


rquotad 


100011 


rquotaprog quota rquota 


sprayd 


100012 


spray 


3270 mapper 


100013 




r je_mapper 


100014 




selection svc 


100015 


selnsvc 


database svc 


100016 




rexd 


100017 


rex 


alis 


100018 




sched 


100019 




llockmgr 


100020 




nlockmgr 


100021 




x25. inr 


100022 




statmon 


100023 




status 


100024 
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FILES 

/etc/rpc 

SEE ALSO 

rpc(3N). 
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NAME 

sccsf ile — format of an SCCS file 

DESCRIPTION 

An SCCS file is an ASCII file. It consists of six logical parts: the 
checksum, the delta table (contains information about each delta), 
user names (contains login names and/or numerical group ID's of 
users who may add deltas), flags (contains definitions of internal 
keywords), comments (contains arbitrary descriptive information 
about the file), and the body (contains the actual text lines inter- 
mixed with control lines). 

Throughout an SCCS file there are lines which begin with the 
ASCII SOH (start of heading) character (octal 001). This charac- 
ter is hereafter referred to as the control character and will be 
represented graphically as @. Any line described below which is 
not depicted as beginning with the control character is prevented 
from beginning with the control character. 

Entries of the form ddddd represent a five-digit string (a number 
between 00000 and 99999). 

Each logical part of an SCCS file is described in detail below. 

checksum 

The checksum is the first line of an SCCS file. The form of 
the line is: 

@hDDDDD 

The value of the checksum is the sum of all characters, ex- 
cept those of the first line. The @h provides a magic number 
of (octal) 064001. 

delta table 

The delta table consists of a variable number of entries of the 
form: 

@s DDDDD/DDDDD/DDDDD 

@d<fype><SCCS ID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 

@i DDDDD... 

@x DDDDD . . . 

@g DDDDD . . . 

@m <MR number> 
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@c <comments> 



@e 

The first line (@s) contains the number of lines 
inserted/deleted/unchanged, respectively. The second line 
(@d) contains the type of the delta (currently, normal: D, 
and removed: R), the SCCS ID of the delta, the date and 
time of creation of the delta, the login name corresponding to 
the real user ID at the time the delta was created, and the 
serial numbers of the delta and its predecessor, respectively. 

The @i, @x, and @g lines contain the serial numbers of 
deltas included, excluded, and ignored, respectively. These 
lines are optional. 

The @m lines (optional) each contain one MR number asso- 
ciated with the delta; the @c lines contain comments associ- 
ated with the delta. 

The @e line ends the delta table entry. 

user names 

The list of login names and/or numeric group ID's of users 
who may add deltas to the file, separated by newlines. The 
lines containing these login names and/or numeric group ID's 
are surrounded by the bracketing lines @u and 6U. An 
empty list allows anyone to make a delta. Any line starting 
with a "!" prohibits the succeeding group or user from 
making deltas. 

flags 

Keywords used internally (see admin(l) for more informa- 
tion on their use). Each flag line takes the form: 

@ f <flag> <optional text> 

The following flags are defined: 
@f t <type of program> 
@f v <program name> 
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@f 


i 


<keyword string> 


6f 


b 




@f 


m 


<module name> 


@f 


f 


<floor> 


@f 


c 


<ceiling> 


@f 


d 


<default-SID> 


@f 


n 




@f 


J 




@f 


1 


<lock-releases> 


@f 


q 


<user defined> 


@f 


z 


<reserved for use in interfaces> 



sccsfile(4) 



The t flag defines the replacement for the %Y% identification 
keyword. The v flag controls prompting for MR numbers in 
addition to comments; if the optional text is present it defines 
an MR number validity checking program. The i flag con- 
trols the warning/error aspect of the "No id keywords" mes- 
sage. When the i flag is not present, this message is only a 
warning; when the i flag is present, this message will cause a 
"fatal" error (the file will not be gotten, or the delta will not 
be made). When the b flag is present the -b keyletter may 
be used on the get command to cause a branch in the delta 
tree. The m flag defines the first choice for the replacement 
text of the %m% identification keyword. The f flag defines 
the "floor" release; the release below which no deltas may 
be added. The c flag defines the "ceiling" release; the 
release above which no deltas may be added. The d flag 
defines the default SID to be used when none is specified on 
a get command. The n flag causes delta to insert a 
"null" delta (a delta that applies no changes) in those 
releases that are skipped when a delta is made in a new 
release (e.g., when delta 5.1 is made after delta 2.7, releases 3 
and 4 are skipped). The absence of the n flag causes skipped 
releases to be completely empty. The j flag causes get to 
allow concurrent edits of the same base SID. The 1 flag 
defines a list of releases that are locked against editing 
(get(l) with the -e keyletter). The q flag defines the re- 
placement for the %Q% identification keyword. The z flag is 
used in certain specialized interface programs. 

comments 

Arbitrary text is surrounded by the bracketing lines @t and 
@T. The comments section typically will contain a descrip- 
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tion of the file's purpose. 

body 

The body consists of text lines and control lines. Text lines 
do not begin with the control character, control lines do. 
There are three kinds of control lines: insert, delete, and end, 
represented by: 

@I DDDDD 
@D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number 
corresponding to the delta for the control line. 

SEE ALSO 

admin(l), cdc(l), comb(l), delta(l), get(l), help(l), 
rmdel(l), sact(l), sccs(l), sccsdiff(l), unget(l), 
val(l), what(l), 

"SCCS Reference" in AIUX Programming Languages and Tools, 
Volume 2. 



February, 1990 

Revision C 



scnhdr(4) 



scnhdr(4) 



NAME 

scnhdr — section header for a common object file 

SYNOPSIS 

♦include <scnhdr.h> 

DESCRIPTION 

Every common object file has a table of section headers to specify 
the layout of the data within the file. Each section within an ob- 
ject file has its own header. The C structure appears below. 



struct scnhdr 








i 

char 




s_name[SYMNMLEN] ; 


/* 


section name */ 


long 




s paddr; 


/* 


physical address */ 


long 




s vaddr; 


/* 


virtual address */ 


long 




s size; 


/* 


section size */ 


long 




s scnptr; 


/* 


file ptr to 
raw data */ 


long 




s relptr; 


/* 


file ptr to 
relocation */ 


long 




s lnnoptr; 


/* 


file ptr to 
line numbers */ 


unsigned 


short 


s nreloc; 


/* 


# reloc entries */ 


unsigned 


short 


s nlnno; 


/* 


# line number 
entries */ 


long 




s flags; 


/* 


flags */ 



} ; 

File pointers are byte offsets into the file; they can be used as the 
offset in a call to f seek(3S). If a section is initialized, the file 
contains the actual bytes. An uninitialized section is somewhat 
different. It has a size, symbols defined in it, and symbols that 
refer to it, but it can have no relocation entries, line numbers, or 
data. Consequently, an uninitialized section has no raw data in the 
object file, and the values for s_scnptr, s_relptr, 
s_lnnoptr, s_nreloc, and s_nlnno are zero. 

SEE ALSO 

ld(l), f seek(3S), a . out (4). 
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NAME 

servers — Internet server database 

DESCRIPTION 

The servers file contains the list of servers that inetd(lM) 
operates. For each server a single line should be present with the 
following information: 

name of server 
protocol 
server location 

If the server is RPC-based, then the name field should be rpc, and 
following the server location are two additional fields, one with 
the RPC program number, the second with either a version 
number or a range of version numbers. 

Items are separated by any number of blanks or tab characters. A 
# indicates the beginning of a comment; characters up to the end 
of the line are not interpreted by routines which search the file. 

The name of the server should be the official service name as con- 
tained in services(4N). The protocol entry is either udp or 
tcp. The server location is the full pathname of the server pro- 
gram. 



EXAMPLES 








tcp 


tcp 


/usr/etc/in . tcpd 




telnet 


tcp 


/usr/etc/in.telnetd 




shell 


tcp 


/etc/in. rshd 




login 


tcp 


/etc/in . rlogind 




exec 


tcp 


/usr/etc/in . rexecd 




tcp 


udp 


/usr/etc/in. ttcpd 




syslog 


udp 


/usr/etc/in . syslog 




comsat 


udp 


/usr/etc/in . comsat 




talk 


udp 


/usr/etc/in . talkd 




time 


tcp 


/usr/etc/in .timed 




rpc 


udp 


/usr/etc/rpc . rstatd 


100001 


rpc 


udp 


/usr/etc/rpc . rusersd 


100002 


rpc 


udp 


/usr/etc/rpc . rwalld 


100008 


rpc 


udp 


/usr/etc/rpc . mountd 


100005 


FILES 








/etc/servers 
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SEE ALSO 

inetd(lM), services (4N) . 

BUGS 

Because of a limitation on the number of open files, this file must 
contain fewer than 27 lines. 
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NAME 

services — service name database 

DESCRIPTION 

The services file contains information regarding the known 
services available in the DARPA Internet. For each service a sin- 
gle line should be present with the following information: 

official service name 
port number 
protocol name 
aliases 

Items are separated by any number of blanks or tab characters. 
The port number and protocol name are considered a single item; 
a / is used to separate the port and protocol (for example, 
512 /tcp). A # indicates the beginning of a comment; characters 
up to the end of the line are not interpreted by routines which 
search the file. 

Service names may contain any printable character other than a 
field delimiter, newline, or comment character. 

FILES 

/etc/services 

SEE ALSO 

getservent(3N). 

BUGS 

A name server should be used instead of a static file. A binary in- 
dexed file format should be available for fast access. 
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NAME 

slip, conf ig — list of slip interfaces supported by a slip 
server 

SYNOPSIS 

/etc/slip. conf ig 

DESCRIPTION 

The slip, conf ig file must be configured on the slip server 
to establish slip connections between the slip client and slip 
host. slip(lM) is a program that assigns a tty line to a network 
interface for a point-to-point TCP/IP link. 

Only the system administrator of the slip server can modify the 
/etc/slip, conf ig file, which contains the slip server host 
address for each of the slip interfaces supported by the slip 
server. mkslipuser(lM) must then be executed to create the 
machine-readable slip . user file from the slip . conf ig data 
file. A sample slip . conf ig configuration file is 

# slip. conf ig configuration file 

# Each line configures a serial line 
# 

128.120.254.3 
128.120.254.3 

In this example, the host has two serial interfaces available for 
slip use. 

SEE ALSO 

netstat(l), dslipuser(lM), if conf ig(lM), 
mkslipuser(lM), slip(lM) slip.hosts(4), 
slip.user(4). 
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NAME 

slip. hosts — map user names to host addresses of slip 
client 

SYNOPSIS 

/etc/ slip. hosts 

DESCRIPTION 

The slip, hosts file must be configured on the slip server to 
establish slip connections between the slip client and the 
slip host slip(lM) is a program that assigns a tty line to a 
network interface for a point-to-point TCP/IP link. 

Only the system administrator of the slip host can modify the 
/etc/ slip. hosts file, which contains the Internet address 
and user name for each user with a slip connection to the slip 
server. A sample slip . hosts file is 

# dialup slip. hosts table 

# maps usercodes to host addresses 
# 

128.120.253.1 joe 

128.120.253.2 chris 

128.120.253.3 mike 

128.120.253.4 linda 

The Internet address in the first field is to be used when the user 
specified in the second field invokes slip. 

SEE ALSO 

netstat(l), dslipuser(lM), if conf ig(lM), 
mkslipuser(lM), slip(lM), slip. conf ig(4), 
slip.user(4). 
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NAME 

slip . user — user file created by mkslipuser 

SYNOPSIS 

/etc/slip. user 

DESCRIPTION 

The slip. user file must be configured on the slip server to 
establish slip connections between the slip client and slip 
host. slip(lM) is a program that assigns a tty line to a network 
interface for a point-to-point TCP/IP link. 

The slip user file /etc/slip. user is not human readable 
and is generated by the command mkslipuser(lM). You can 
use the command dslipuser(lM) to display the contents of the 
user file, which reports the number of slip users on the system 
and the number of available slip interfaces. 

SEE ALSO 

netstat(l), dslipuser(lM), if conf ig(lM), 
mkslipuser(lM), slip(lM), slip. conf ig(4), 
slip.hosts(4). 
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NAME 

svf s — format of a System V system volume 

SYNOPSIS 

♦include <sys / types .h> 
♦include <sys/param.h> 
♦include <svfs/filsys.h> 

DESCRIPTION 

Every SVFS file-system storage volume has a common format for 
certain vital information. Each volume is divided into a certain 
number of 512-byte sectors. Sector contains the disk partition 
map. See dpme(4) for further information on its structure. 

Sector 1 is the superblock. The format of a superblock is 



/* 



* Structure of the superblock 
*/ 



struct filsys 






ushort 


s isize; 


/* 


size in blocks 








of i-list */ 


daddr t 


s fsize; 


/* 


size in blocks of 
entire volume */ 


short 


s nfree; 


/* 


number of addresses 








in s free */ 


daddr t 


s_free[NICFREE]; 


/* 


free block list */ 


short 


s ninode; 


/* 


number of inodes 








in s inode */ 


ino t 


s_inode[NICINOD] ; 


/* 


free inode list */ 


char 


s flock; 


/* 


lock during free 
list manipulation */ 


char 


s ilock; 


/* 


lock during i-list 
manipulation */ 


char 


s fmod; 


/* 


superblock modified 
flag */ 


char 


s ronly; 


/* 


mounted read-only 








flag */ 


time t 


s time; 


/* 


last superblock 








update */ 


short 


s dinfo[4] ; 


/* 


device information */ 


daddr t 


s tfree; 


/* 


total free blocks */ 


ino t 


s tinode; 


/* 


total free inodes */ 


char 


s fname[6] ; 


/* 


file-system name */ 


char 


s fpack[6] ; 


/* 


file-system pack name */ 


long 


s_fill[13]; 


/* 


ADJUST size of 
filsys to 512 */ 


long 


s state; 




/* file-system state 


ino t 


s lasti; 


/* 


start place for 
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circular search */ 
ino_t s_nbehind; /* est # free i nodes 

before s_lasti */ 
long s_magic; /* magic number to 

indicate new filesys */ 
long s_type; /* type of new filesys */ 



}; 



#define FsMAGIC 0xfdl87e20 /* s_magic number */ 

#define Fslb 1 /* 512-byte block */ 

tdefine Fs2b 2 /* 1024-byte block */ 

#define Fs4b 4 /* 2048-byte block */ 

s_type indicates the file-system type. Currently, two types of 
file systems are supported: the original 512-byte block system and 
the new improved 1024-byte block system. s_magic is used to 
distinguish the original 512-byte block file systems from the 
newer file systems. If this field is not equal to the magic number, 
FsMAGIC, the type is assumed to be Fslb; otherwise, the 
s_type field is used. In the following description, a block is 
then determined by the type. For the original 512-byte block file 
system, a block is 512 bytes. For the 1024-byte block file system, 
a block is 1024 bytes or two sectors. The operating system takes 
care of all conversions from logical block numbers to physical 
sector numbers. 

s_isize is the address of the first data block after the inode list. 
The i-list starts just after the superblock, namely in block 2; thus 
the i-list is s_isize-2 blocks long. s_f size is the first block 
not potentially available for allocation to a file. These numbers 
are used by the system to check for bad block numbers. If an 
"impossible" block number is allocated from the free list or is 
freed, a diagnostic is written on the online console. Moreover, the 
free array is cleared, to prevent further allocation from a presum- 
ably corrupted free list 

The free list for each volume is maintained as follows. The 
s_free array contains, in s_free[l]... 

s_free[s_nfree-l], up to 49 numbers of free blocks. 
s_f ree [ ] is the block number of the head of a chain of blocks 
constituting the free list. The first long in each free-chain block is 
the number (up to 50) of free-block numbers listed in the next 50 
longs of this chain member. The first of these 50 blocks is the link 
to the next member of the chain. 
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To allocate a block, decrement s_nf ree, and the new block is 
s_f ree [s_nf ree] . If the new block number is 0, there are no 
blocks left, so give an error. If s_nf ree became 0, read in the 
block named by the new block number, replace s_nf ree by its 
first word, and copy the block numbers in the next 50 longs into 
the s_f ree array. 

To free a block, check if s_nf ree is 50. If so, copy s_nf ree 
and the s_f ree array into it, write it out, and set s_nf ree to 0. 
In any event, set s_f ree [ s_nf ree ] to the number of the freed 
block and increment s_nf ree. 

s_tf ree is the total free blocks available in the file system. 

s_ninode is the number of free inumbers in the s_inode ar- 
ray. To allocate an inode, if s_ninode is greater than 0, decre- 
ment it and return s_inode [ s_ninode] . To allocate an inode, 
if s_ninode is 0, read the i-list, place the numbers of all free 
inodes (up to 100) into the s_inode array, and then try again. 
To free an inode, provided s_ninode is less than 100, place its 
number into s_inode [s_ninode] and increment s_ninode. 
If s_ninode is already 100, do not bother to enter the freed 
inode into any table. This list of inodes is only to speed up the al- 
location process. The information as to whether the inode is really 
free or not is maintained in the inode itself. 

s_t inode is the total free inodes available in the file system. 

s_flock and s_ilock are flags maintained in the memory 
copy of the file system while it is mounted, and their values on 
disk are immaterial. The value of s_f mod on disk is likewise im- 
material because it is used as a flag to indicate that the superblock 
has changed and should be copied to the disk during the next 
periodic update of file-system information. 

sronly is a read-only flag to indicate write-protection. 

s_time is the last time the superblock of the file system was 
changed and is the number of seconds that have elapsed since 
00:00 January 1, 1970 (GMT). During a reboot, the s_time of 
the superblock for the root file system is used to set the system's 
idea of the time. 

s_f name is the name of the file system, and s_f pack is the 
name of the pack. 
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Inumbers begin at 1, and the storage for inodes begins in block 2. 
Also, inodes are 64 bytes long. Inode 1 is reserved for future use. 
Inode 2 is reserved for the root directory of the file system, but no 
other inumber has a built-in meaning. Each inode represents one 
file. For the format of an inode and its flags, see inode(4). 

FILES 

/usr/include/svf s/f ilsys . h 
/usr/include/sys/stat .h 

SEE ALSO 

f sck(lM), f sdb(lM), mkf s(lM), dpme(4), uf s(4), 
inode(4). 
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NAME 

syms — common object file symbol table format 

SYNOPSIS 

♦include <syms . h> 

DESCRIPTION 

Common object files contain information to support symbolic 
software testing (see sdb(l)). Line number entries, linenum(4), 
and extensive symbolic information permit testing at the C source 
level. Every object file's symbol table is organized as shown. 

Filename 1. 

Function 1. 

Local symbols for function 1. 
Function 2 

Local symbols for function 2. 

Static externs for file 1. 

Filename 2. 

Function 1. 

Local symbols for function 1. 
Function 2. 

Local symbols for function 2. 

Static externs for file 2. 



Defined global symbols. 
Undefined global symbols. 

The entry for a symbol is a fixed-length structure. The members 
of the structure hold the name (null padded), its value, and other 
information. The C structure is 

# define SYMNMLEN 8 
# define FILNMLEN 14 
#define DIMNUM 4 

struct syment 
{ 
union /* ways to get a 

symbol name */ 
{ 

char _n_name [SYMNMLEN] ; /* names less than 

8 chars */ 
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n zeroes; 



n offset; 



struct 

{ 

long 

long 

} _n_n; 
char 
_n; 
long 

short _ 

unsigned short n_type 



'* names 8 char 
or more */ 

/* == OL when in 
string table */ 

/* location of name 
table */ 



* n_nptr[2]; /* allows overlaying */ 



char 
char 
}; 

# define 
#define 
#define 
#define 



n_value ; /* value of symbol */ 
n_scnum ; /* section number */ 

/* tyP e anc * derived type */ 
sclass ; /*storage class */ 
numaux ; /* number of aux entries */ 



n_name 
n_zeroes 
n_of fset 
n nptr 



_n._n_name 
_n . _n_n . _n_z e r oe s 
_n . _n_n . _n_o f f set 
_n . _n_npt r [ 1 ] 



Meaningful values and explanations are given in both syms . h 
and Common Object File Format. Anyone who needs to interpret 
the entries should seek more information in these sources. Some 
symbols require more information than a single entry; they are fol- 
lowed by auxiliary entries that are the same size as a symbol en- 
try. The format is as follows. 

union auxent 
{ 

struct 

{ 



long 

union 

{ 



long 
} x_misc; 
union 
{ 

struct 

{ 



struct 
{ 



xtagndx; 



struct 

{ 

unsigned short x 
unsigned short x 

} x_lnsz; 

< fsize; 



lnno; 
size; 



long 
long 
x fen; 



_lnnoptr; 
endndx; 



February, 1990 

Revision C 



syms(4) syms(4) 



x dimen[DIMNUM] 





unsigned short 




} x_ary; 

} x_fcnary; 
unsigned short x tvndx; 


} 

struct 
{ 

} 


x_sym; 


char x_f name [FILNMLEN] ; 
x file; 


struct 
{ 





long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 
} x_scn; 

struct 
{ 

unsigned short x_tvlen; 

unsigned short x_tvran[2]; 
} x tv; 



}; 



Indexes of symbol table entries begin at zero. 

SEE ALSO 

sdb(l), a . out(4), linenum(4). 

"COFF Reference' ' in AIUX Programming Languages and Tools, 

Volume 2. 

WARNINGS 

In machines in which a long are equivalent to an int (M68000 
and VAX), the long is converted to int in the compiler to 
minimize the complexity of the compiler code generator. Thus, 
the information about which symbols are declared as long and 
which as int cannot be determined from the symbol table. 
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NAME 

tar — format of tar header 

DESCRIPTION 

tar saves and restores files on magnetic tape or floppy disks. 
The tar header format is as follows: 

# define TBLOCK 512 

# define NBLOCK 40 

# define NAMSIZ 100 
union hblock { 

char dummy [TBLOCK] ; 
struct header { 

char name [NAMESIZ] ; 

char mode [ 8 ] ; 

char uid[8] ; 

char gid[8] ; 

char size [12] ; 

char mtime [ 12 ] ; 

char chksum[8]; 

char linkflag; 

char linkname [NAMESIZ] ; 
} dbuf; 
} dblock, tbuf [NBLOCK] ; 

SEE ALSO 

tar(l). 
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NAME 

term — format of compiled term file 

SYNOPSIS 

term 

DESCRIPTION 

Compiled terminf o descriptions are placed under the directory 
/usr/lib/terminf o. In order to avoid a linear search of a 
huge A/UX system directory, a two-level scheme is used: 
/usr/lib/terminf o/c/name where name is the name of the 
terminal, and c is the first character of name. Thus, act 4 can be 
found in the file /usr/lib/terminfo/a/act4. Synonyms 
for the same terminal are implemented by multiple links to the 
same compiled file. 

The format has been chosen so that it will be the same on all 
hardware. An 8 or more bit byte is assumed, but no assumptions 
about byte ordering or sign extension are made. 

The compiled file is created with the tic(lM) program, and read 
by the routine setupterm. Both of these pieces of software are 
part of curses(3X). The file is divided into six parts: the 
header, terminal names, boolean flags, numbers, strings, and string 
table. 

The header section begins the file. This section contains six short 
integers in the format described below. These integers are: (1) 
the magic number (octal 0432); (2) the size, in bytes, of the names 
section; (3) the number of bytes in the boolean section; (4) the 
number of short integers in the numbers section; (5) the number of 
offsets (short integers) in the strings section; (6) the size, in bytes, 
of the string table. 

Short integers are stored in two 8-bit bytes. The first byte contains 
the least significant 8 bits of the value, and the second byte con- 
tains the most significant 8 bits. (Thus, the value represented is 
256*second+first.) The value -1 is represented by 0377, 0377, 
other negative value are illegal. The -1 generally means that a ca- 
pability is missing from this terminal. Computers where this does 
not correspond to the hardware read the integers as two bytes and 
compute the result. 

The terminal names section comes next. It contains the first line 
of the terminf o description, listing the various names for the 
terminal, separated by the "I" character. The section is terminat- 
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ed with an ASCII NUL character. 

The boolean flags have one byte for each flag. This byte is either 
or 1 as the flag is present or absent. The capabilities are in the 
same order as the file <term. h>. 

Between the boolean section and the number section, a null byte 
will be inserted, if necessary, to ensure that the number section be- 
gins on an even byte. All short integers are aligned on a short 
word boundary. 

The numbers section is similar to the flags section. Each capabili- 
ty takes up two bytes, and is stored as a short integer. If the value 
represented is -1, the capability is taken to be missing. 

The strings section is also similar. Each capability is stored as a 
short integer, in the format above. A value of -1 means the capa- 
bility is missing. Otherwise, the value is taken as an offset from 
the beginning of the string table. Special characters in Control-* 
or V notation are stored in their interpreted form, not the printing 
representation. Padding information $<nn> and parameter infor- 
mation %x are stored intact in uninterpreted form. 

The final section is the string table. It contains all the values of 
string capabilities referenced in the string section. Each string is 
null terminated. 

Note that it is possible for setupterm to expect a different set of 
capabilities than are actually present in the file. Either the data- 
base may have been updated since setupterm has been recom- 
piled (resulting in extra unrecognized entries in the file) or the 
program may have been recompiled more recently than the data- 
base was updated (resulting in missing entries). The routine 
setupterm must be prepared for both possibilities - this is why 
the numbers and sizes are included. Also, new capabilities must 
always be added at the end of the lists of boolean, number, and 
string capabilities. 

As an example, an octal dump of the description for the Micro- 
term ACT 4 is included: 

microterml act4 Imicroterm act iv, 

cr=~M, cudl = "J, ind="J, bel="G, am, cubl = "H, 
ed="_, el=~", clear="L, cup=' v T%pl%c%p2%c, 
cols#80, lines#24, cufl = "X, cuul=~Z, home=' N ], 
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000 032 001 \0 025 \0 \b \0 212 \0 " \0 m i c r 

020 oterml act4 | micro 

040 term act i v \0 \0 001 \0 \0 

060 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 

100 \0 \0 P \0 377 377 030 \0 377 377 377 377 377 377 377 377 

120 377 377 377 377 \0 \0 002 \0 377 377 377 377 004 \0 006 \0 

140 \b \0 377 377 377 377 \n \0 026 \0 030 \0 377 377 032 \0 

160 377 377 377 377 034 \0 377 377 036 \0 377 377 377 377 377 377 

200 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 

520 377 377 377 377 \0 377 377 377 377 377 377 377 377 377 377 
540 377 377 377 377 377 377 007 \0 \r \0 \f \0 036 \0 037 \0 
560 024 % p 1 % c % p 2 % c \0 \n \0 035 \0 
600 \b \0 030 \0 032 \0 \n \0 

Some limitations: total compiled entries cannot exceed 4096 
bytes. The name field cannot exceed 128 bytes. 

FILES 

/usr/lib/terminfo/*/* 

compiled terminal capability data base 

SEE ALSO 

curses(3X), terminf o(4). 
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NAME 

termcap — terminal capability database 

SYNOPSIS 

/etc/termcap 

DESCRIPTION 

termcap is a data base describing terminals used, for example 
by vi(l). Terminals are described in termcap by giving a set of 
capabilities which they have and by describing how operations are 
performed. Padding requirements and initialization sequences are 
included in termcap. 

Entries in termcap consist of a number of colon (:) separated 
fields. The first entry for each terminal gives the names which are 
known for the terminal, separated by | characters. The first name 
is always 2 characters long and is used by older version 6 systems 
which store the terminal type in a 16 bit word in a system wide 
data base. The second name given is the most common abbrevia- 
tion for the terminal, and the last name given should be a long 
name fully identifying the terminal. The second name should con- 
tain no blanks; the last name may well contain blanks for readabil- 
ity. 

CAPABILITIES 

(P) indicates padding may be specified 

(P*) indicates that padding may be based on no. lines affected 

Description 

End alternate character set 
Add new blank line 
Terminal has automatic margins 
Start alternate character set 
Backspace if not Control-H 
Terminal can backspace with Control-H 
Back tab 

Backspace wraps from column to last column 
Command character in prototype if terminal settable 
Clear to end of display 
Clear to end of line 

Like cm but horizontal motion only, line stays same 
Clear screen 
Cursor motion 
Number of columns in a line 
(P*) Carriage return, (default Control-M) 
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Name 


Type 


Pad? 


ae 


str 


(P) 


al 


str 


(P*) 


am 


bool 




as 


str 


(P) 


be 


str 




bs 


bool 




bt 


str 


(P) 


bw 


bool 




CC 


str 




cd 


str 


(P*) 


ce 


str 


(P) 


ch 


str 


(P) 


cl 


str 


(P*) 


cm 


str 


(P) 
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Change scrolling region (vtlOO), like cm 

Like ch but vertical only. 

Display may be retained above 

Number of millisec of bs delay needed 

Display may be retained below 

Number of millisec of cr delay needed 

Delete character 

Number of millisec of f f delay needed 

Delete line 

Delete mode (enter) 

Number of millisec of n 1 delay needed 

Down one line 

Number of millisec of tab delay needed 

End delete mode 

End insert mode; give :ei=: if ic 

Can erase overstrikes with a blank 

Hardcopy terminal page eject (default Control-L) 

Hardcopy terminal 

Half -line down (forward 1/2 linefeed) 

Home cursor (if no cm) 

Half -line up (reverse 1/2 linefeed) 

Hazeltine; can't print ~'s 

Insert character 

Name of file containing i s 

Insert mode (enter); give : im= : if ic 

Insert mode distinguishes nulls on display 

Insert pad after character inserted 

Terminal initialization string 

Sent by "other" function keys 0-9 

Sent by backspace key 

Sent by terminal down arrow key 

Out of "keypad transmit" mode 

Sent by home key 

Sent by terminal left arrow key 

Number of "other' ' keys 

Termcap entries for other non-function keys 

Sent by terminal right arrow key 

Put terminal in "keypad transmit" mode 

Sent by terminal up arrow key 

Labels on "other" function keys 

Number of lines on screen or page 

Last line, first column (if no cm) 



cs 


str 


(P) 


cv 


str 


(P) 


da 


bool 




dB 


num 




db 


bool 




dC 


num 




dc 


str 


(P*) 


dF 


num 




dl 


str 


(P*) 


dm 


str 




dN 


num 




do 


str 




dT 


num 




ed 


str 




ei 


str 




eo 


str 




ff 


str 


(P*) 


he 


bool 




hd 


str 




ho 


str 




hu 


str 




hz 


str 




ic 


str 


(P) 


if 


str 




im 


str 




in 


bool 




ip 


str 


(P*) 


is 


str 




kO- 


■k9 str 




kb 


str 




kd 


str 




ke 


str 




kh 


str 




kl 


str 




kn 


num 




ko 


str 




kr 


str 




ks 


str 




ku 


str 




lu- 


•19 str 




ll 


num 




11 


str 
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Arrow key map, used by vi version 2 only 

Safe to move while in insert mode 

Memory lock on above cursor. 

Safe to move while in standout and underline mode 

Memory unlock (turn off memory lock). 

No correctly working carriage return (DM2500.H2000) 

Non-destructive space (cursor right) 

Newline character (default \n) 

Terminal is a CRT but doesn't scroll. 

Terminal overstrikes 

Pad character (rather than null) 

Has hardware tabs (may need to be set with i s) 

End stand out mode 

Scroll forwards 

Number of blank chars left by so or se 

Begin stand out mode 

Scroll reverse (backwards) 

Tab (other than Control-I or with padding) 

Entry of similar terminal - must be last 

String to end programs that use cm 

String to begin programs that use cm 

Underscore one char and move past it 

End underscore mode 

Number of blank chars left by u s or ue 

Terminal underlines even though it doesn't 

overstrike 

Upline (cursor up) 

Start underscore mode 

Visible bell (may not move cursor) 

Sequence to end open/visual mode 

Sequence to start open/visual mode 

Beehive (f l=escape, f 2=ctrl C) 

A newline is ignored after a wrap (Concept) 

Return acts like ce \r \n (Delta Data) 

Standout not erased by writing over it (HP 264?) 

Tabs are destructive, magic so char (Teleray 1061) 

A Sample Entry 

The following entry, which describes the Concept- 100, is among 
the more complex entries in the termcap file as of this writing. 
(This particular concept entry is outdated and is used as an exam- 
ple only.) 
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ma 


str 




mi 


bool 




ml 


str 




ms 


bool 




mu 


str 




nc 


bool 




nd 


str 




nl 


str 


(P* 


ns 


bool 




OS 


bool 




pc 


str 




pt 


bool 




se 


str 




sf 


str 


(P) 


sg 


num 




so 


str 




sr 


str 


(P) 


ta 


str 


(P) 


tc 


str 




te 


str 




ti 


str 




uc 


str 




ue 


str 




ug 


num 




ul 


bool 




up 


str 




us 


str 




vb 


str 




ve 


str 




vs 


str 




xb 


bool 




xn 


bool 




xr 


bool 




xs 


bool 




xt 


bool 
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cl clOO conceptlOO:is=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200:\ 

:al=3*\E~R:am:bs:cd=16*\E~C:ce=16\E~S:cl=2*~L\ 

:cm=\Ea%+ %+ :co#80:\ :dc=16\E~A:dl=3*\E~B\ 

:ei=\E\200:eo:im=\E~P:in:ip=16*:li#24:mi:nd=\E=:\ 

: se=\Ed\Ee : so=\ED\EE : t a=8\t : ul : up=\E; : vb=\Ek\EK: xn : 

Entries may continue onto multiple lines by giving a \ as the last 
character of a line, and that empty fields may be included for rea- 
dability (here between the last field on a line and the first field on 
the next). Capabilities in termcap are of three types: Boolean 
capabilities which indicate that the terminal has some particular 
feature, numeric capabilities giving the size of the terminal or the 
size of particular delays, and string capabilities, which give a se- 
quence which can be used to perform particular terminal opera- 
tions. 

Types of Capabilities 

All capabilities have two letter codes. For instance, the fact that 
the Concept has automatic margins (that is, an automatic return 
and linefeed when the end of a line is reached) is indicated by the 
capability am. Hence the description of the Concept includes am. 
Numeric capabilities are followed by the character "#" and then 
the value. Thus co which indicates the number of columns the 
terminal has gives the value "80" for the Concept. 

Finally, string valued capabilities, such as ce (clear to end of line 
sequence) are given by the two character code, an "=", and then a 
string ending at the next following ":". A delay in milliseconds 
may appear after the "=" in such a capability, and padding char- 
acters are supplied by the editor after the remainder of the string is 
sent to provide this delay. The delay can be either a integer, e.g., 
"20", or an integer followed by an "*", i.e. "3*". A "*" indi- 
cates that the padding required is proportional to the number of 
lines affected by the operation, and the amount given is the per- 
affected-unit padding required. When a "*" is specified, it is 
sometimes useful to give a delay of the form "3.5" specify a de- 
lay per unit to tenths of milliseconds. 

A number of escape sequences are provided in the string valued 
capabilities for easy encoding of characters there. A \E maps to 
an escape character, Control-X maps to a Control-* for any 
appropriate x, and the sequences \n, \r, \tr, \b, and \f give a 
newline, return, tab, backspace and form feed. Finally, characters 
may be given as three octal digits after a \, and the characters " 
and \ may be given as \ * and \ \. If it is necessary to place a 
: in a capability it must be escaped in octal as \072. If it is 
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necessary to place a null character in a string capability it must be 
encoded as \200. The routines which deal with termcap use 
C strings, and strip the high bits of the output very late so that a 
\ 2 comes out as a \ would. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The 
most effective way to prepare a terminal description is by imitat- 
ing the description of a similar terminal in termcap and to build 
up a description gradually, using partial descriptions with ex to 
check that they are correct. Be aware that a very unusual terminal 
may expose deficiencies in the ability of the termcap file to 
describe it or bugs in ex. To easily test a new terminal descrip- 
tion you can set the environment variable termcap to a path- 
name of a file containing the description you are working on and 
the editor will look there rather than in /etc /termcap. 
TERMCAP can also be set to the termcap entry itself to avoid 
reading the file when starting up the editor. (This only works on 
version 7 systems.) 

Basic Capabilities 

The number of columns on each line for the terminal is given by 
the co numeric capability. If the terminal is a CRT, then the 
number of lines on the screen is given by the li capability. If the 
terminal wraps around to the beginning of the next line when it 
reaches the right margin, then it should have the am capability. If 
the terminal can clear its screen, then this is given by the cl string 
capability. If the terminal can backspace, then it should have the 
bs capability, unless a backspace is accomplished by a character 
other than Control-H, in which case you should give this charac- 
ter as the be string capability. If it overstrikes (rather than clear- 
ing a position when a character is struck over) then it should have 
the os capability. 

A very important point here is that the local cursor motions encod- 
ed in termcap are undefined at the left and top edges of a CRT 
terminal. The editor will never attempt to backspace around the 
left edge, nor will it attempt to go up locally off the top. The edi- 
tor assumes that feeding off the bottom of the screen will cause 
the screen to scroll up, and the am capability tells whether the cur- 
sor sticks at the right edge of the screen. If the terminal has 
switch selectable automatic margins, the termcap file usually as- 
sumes that this is on, i.e. am. 
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These capabilities suffice to describe hardcopy and "glass-tty" 
terminals. Thus the model 33 teletype is described as 

t3 I 33 | tty33 : co#72 : os 

while the Lear Siegler ADM-3 is described as 

cl|adm3| 3|lsi adm3:am:bs:cl=~Z :li#24 :co#80 

Cursor Addressing 

Cursor addressing in the terminal is described by a cm string capa- 
bility, with print f(3S) like escapes %x in it. These substitute to 
encodings of the current line or column position, while other char- 
acters are passed through unchanged. If the cm string is thought 
of as being a function, then its arguments are the line and then the 
column to which motion is desired, and the % encodings have the 
following meanings: 

%d as in printf, origin 

%2 like %2d 

%3 like%3d 

% . like %c 

% +x adds x to value, then %. 

% >xy if value > x adds v, no output. 

% r reverses order of line and column, no output 

%i increments line/column (for 1 origin) 

%% gives a single % 

%n exclusive or row and column with 0140 (DM2500) 

%B BCD (16*(x/10) ) + (x%10), no output. 

%D Reverse coding (x-2 * (x% 1 6 ) ), no output. (Delta Data). 

Consider the HP2645, which, to get to row 3 and column 12, 
needs to be sent \E&al2c03Y padded for 6 milliseconds. Note 
that the order of the rows and columns is inverted here, and that 
the row and column are printed as two digits. Thus its cm capa- 
bility is "cm=6\E&%r%2c%2Y." The Microterm ACT-IV needs 
the current row and column sent preceded by a Control-T, with 
the row and column simply encoded in binary, "cm=CONTROL- 
T% . %.". Terminals which use **% . " need to be able to back- 
space the cursor (bs or be), and to move the cursor up one line 
on the screen (up introduced below). This is necessary because it 
is not always safe to transmit \t, \n, Control-D, and \r, as 
the system may change or discard them. 
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A final example is the LSI ADM-3a, which uses row and column 
offset by a blank character, thus 

cm=\E=%+ %+ 

Cursor Motions 

If the terminal can move the cursor one position to the right, leav- 
ing the character at the current position unchanged, then this se- 
quence should be given as nd (nondestructive space). If it can 
move the cursor up a line on the screen in the same column, this 
should be given as up. If the terminal has no cursor addressing 
capability, but can home the cursor (to very upper left corner of 
screen) then this can be given as ho; similarly a fast way of get- 
ting to the lower left hand corner can be given as 11; this may in- 
volve going up with up from the home position, but the editor will 
never do this itself (unless 11 does) because it makes no assump- 
tion about the effect of moving up from the home position. 

Area Clears 

If the terminal can clear from the current position to the end of the 
line, leaving the cursor where it is, this should be given as ce. If 
the terminal can clear from the current position to the end of the 
display, then this should be given as cd. The editor only uses 
cd from the first column of a line. 

Insert/Delete Line 

If the terminal can open a new blank line before the line where the 
cursor is, this should be given as al; this is done only from the 
first position of a line. The cursor must then appear on the newly 
blank line. If the terminal can delete the line which the cursor is 
on, then this should be given as dl; this is done only from the 
first position on the line to be deleted. If the terminal can scroll 
the screen backwards, then this can be given as sb, but just al 
suffices. If the terminal can retain display memory above then the 
da capability should be given; if display memory can be retained 
below then db should be given. These let the editor understand 
that deleting a line on the screen may bring non-blank lines up 
from below or that scrolling back with sb may bring down non- 
blank lines. 

Insert/Delete Character 

There are two basic kinds of intelligent terminals with respect to 
insert/delete character which can be described using termcap. 
The most common insert/delete character operations affect only 
the characters on the current line and shift characters off the end 
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of the line rigidly. Other terminals, such as the Concept 100 and 
the Perkin Elmer Owl, make a distinction between typed and un- 
typed blanks on the screen, shifting upon an insert or delete only 
to an untyped blank on the screen which is either eliminated, or 
expanded to two untyped blanks. You can find out which kind of 
terminal you have by clearing the screen and then typing text 
separated by cursor motions. Type "abc def" using local 
cursor motions (not spaces) between the "abc" and the "def". 
Then position the cursor before the "abc" and put the terminal in 
insert mode. If typing characters causes the rest of the line to shift 
rigidly and characters to fall off the end, then your terminal does 
not distinguish between blanks and untyped positions. If the 
"abc" shifts over to the "def" which then move together 
around the end of the current line and onto the next as you insert, 
you have the second type of terminal, and should give the capabil- 
ity in, which stands for "insert null". If your terminal does 
something different and unusual then you may have to modify the 
editor to get it to use the insert mode your terminal defines. We 
have seen no terminals which have an insert mode not falling into 
one of these two classes. 

The editor can handle both terminals which have an insert mode, 
and terminals which send a simple sequence to open a blank posi- 
tion on the current line. Give as im the sequence to get into in- 
sert mode, or give it an empty value if your terminal uses a se- 
quence to insert a blank position. Give as ei the sequence to 
leave insert mode (give this, with an empty value also if you gave 
im so). Now give as ic any sequence needed to be sent just be- 
fore sending the character to be inserted. Most terminals with a 
true insert mode will not give ic, terminals which send a se- 
quence to open a screen position should give it here. (Insert mode 
is preferable to the sequence to open a position on the screen if 
your terminal has both.) If post insert padding is needed, give this 
as a number of milliseconds in ip (a string option). Any other 
sequence which may need to be sent after an insert of a single 
character may also be given in ip. 

It is occasionally necessary to move around while in insert mode 
to delete characters on the same line (e.g. if there is a tab after the 
insertion position). If your terminal allows motion while in insert 
mode you can give the capability mi to speed up inserting in this 
case. Omitting mi will affect only speed. Some terminals (not- 
ably Datamedia's) must not have mi because of the way their in- 
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sert mode works. 

Finally, you can specify delete mode by giving dm and ed to 
enter and exit delete mode, and dc to delete a single character 
while in delete mode. 

Highlighting, Underlining, and Visible Bells 
If your terminal has sequences to enter and exit standout mode, 
these can be given as so and se, respectively. If there are 
several flavors of standout mode (such as inverse video, blinking, 
or underlining; half bright is not usually an acceptable "standout" 
mode unless the terminal is in inverse video mode constantly) the 
preferred mode is inverse video by itself. If the code to change 
into or out of standout mode leaves one or even two blank spaces 
on the screen, as the TVI 912 and Teleray 1061 do, then ug 
should be given to tell how many spaces are left. 

Codes to begin underlining and end underlining can be given as 
us and ue respectively. If the terminal has a code to underline 
the current character and move the cursor one space to the right, 
such as the Microterm Mime, this can be given as uc. (If the 
underline code does not move the cursor to the right, give the code 
followed by a nondestructive space.) 

Many terminals, such as the HP 2621, automatically leave stan- 
dout mode when they move to a new line or the cursor is ad- 
dressed. Programs using standout mode should exit standout 
mode before moving the cursor or sending a newline. 

If the terminal has a way of flashing the screen to indicate an error 
quietly (a bell replacement) then this can be given as vb; it must 
not move the cursor. If the terminal should be placed in a dif- 
ferent mode during open and visual modes of ex, this can be given 
as vs and ve, sent at the start and end of these modes respec- 
tively. These can be used to change, e.g., from a underline to a 
block cursor and back. 

If the terminal needs to be in a special mode when running a pro- 
gram that addresses the cursor, the codes to enter and exit this 
mode can be given as ti and te. This arises, for example, from 
terminals like the Concept with more than one page of memory. If 
the terminal has only memory relative cursor addressing and not 
screen relative cursor addressing, a one screen-sized window must 
be fixed into the terminal for cursor addressing to work properly. 
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If your terminal correctly generates underlined characters (with no 
special codes needed) even though it does not overstrike, then you 
should give the capability ul. If overstrikes are erasable with a 
blank, then this should be indicated by giving eo. 

Keypad 

If the terminal has a keypad that transmits codes when the keys 
are pressed, this information can be given. Note that it is not pos- 
sible to handle terminals where the keypad only works in local 
(this applies, for example, to the unshifted HP 2621 keys). If the 
keypad can be set to transmit or not transmit, give these codes as 
ks and ke. Otherwise the keypad is assumed to always transmit. 
The codes sent by the left arrow, right arrow, up arrow, down ar- 
row, and home keys can be given as kl, kr, ku, kd, and 
kh respectively. If there are function keys such as fO, fl, . . ., f9, 
the codes they send can be given as kO, kl, ..., k9. If these 
keys have labels other than the default fO through f9, the labels 
can be given as 10, 11, ..., 19. If there are other keys that 
transmit the same code as the terminal expects for the correspond- 
ing function, such as clear screen, the termcap 2 letter codes can 
be given in the ko capability, for example, 
" : ko=cl , 11, sf , sb: ", which says that the terminal has clear, 
home down, scroll down, and scroll up keys that transmit the same 
thing as the cl, 11, sf , and sb entries. 

The ma entry is also used to indicate arrow keys on terminals 
which have single character arrow keys. It is obsolete but still in 
use in version 2 of vi, which must be run on some minicomputers 
due to memory limitations. This field is redundant with kl, kr, 
ku, kd, and kh. It consists of groups of two characters. In each 
group, the first character is what an arrow key sends, the second 
character is the corresponding vi command. These commands 
are h for kl, j for kd, k for ku, 1 for kr, and H for kh. For ex- 
ample, the mime would be :ma=~Kj~Zk'*Xl : indicating arrow 
keys left (Control-Ii), down (Control-K), up (Control-Z), 
and right (Control-X). (There is no home key on the mime.) 

Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, 
then this can be given as pc. 

If tabs on the terminal require padding, or if the terminal uses a 
character other than Control-I to tab, then this can be given as 

ta. 
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Hazeltine tenninals, which don't allow "~" characters to be print- 
ed should indicate hz. Datamedia terminals, which echo 
carriage-return linefeed for carriage return and then ignore a fol- 
lowing linefeed should indicate nc. Early Concept terminals, 
which ignore a linefeed immediately after an am wrap, should in- 
dicate xn. If an erase-eol is required to get rid of standout (in- 
stead of merely writing on top of it), xs should be given. Teleray 
terminals, where tabs turn all characters moved over to blanks, 
should indicate xt. Other specific terminal problems may be 
corrected by adding more capabilities of the form xx. 

Other capabilities include is, an initialization string for the ter- 
minal, and if , the name of a file containing long initialization 
strings. These strings are expected to properly clear and then set 
the tabs on the terminal, if the terminal has settable tabs. If both 
are given, is will be printed before if. This is useful where 
if is /usr/lib/tabset/stdbut is clears the tabs first. 

Similar Tenninals 

If there are two very similar terminals, one can be defined as being 
just like the other with certain exceptions. The string capability 
tc can be given with the name of the similar terminal. This capa- 
bility must be last and the combined length of the two entries must 
not exceed 1024. Since termlib routines search the entry from 
left to right, and since the tc capability is replaced by the 
corresponding entry, the capabilities given at the left override the 
ones in the similar terminal. A capability can be cancelled with 
xx@ where xx is the capability. For example, the entry: 

hn | 2621nl:ks@:ke@:tc=2 621: 

defines a "2621nl" that does not have the ks or ke capabilities, 
and hence does not turn on the function key labels when in visual 
mode. This is useful for different modes for a terminal, or for dif- 
ferent user preferences. 

FILES 

/ e t c / 1 e rmc ap file containing terminal descriptions 

SEE ALSO 

ex(l), tset(l), ul(l), vi(l), termcap(3X). 

BUGS 

ex allows only 256 characters for string capabilities, and the rou- 
tines in termcap (3X) do not check for overflow of this buffer. 
The total length of a single entry (excluding only escaped new- 
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lines) may not exceed 1024. 

The ma, vs, and ve entries are specific to the vi program. 

Not all programs support all entries. There are entries that are not 
supported by any program. 
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NAME 

terminf o — terminal capability database 

SYNOPSIS 

/usr/lib/terminfo/*/* 

DESCRIPTION 

terminf o is a data base describing terminals, used for example 
by vi(l) and curses(3X). Terminals are described in ter- 
minf o by giving a set of capabilities which they have, and by 
describing how operations are performed. Padding requirements 
and initialization sequences are included in terminf o. 

Entries in terminf o consist of a number of "," separated fields. 
White space after each "," is ignored. The first entry for each 
terminal gives the names which are known for the terminal, 
separated by "I" characters. The first name given is the most 
common abbreviation for the terminal, the last name given should 
be a long name fully identifying the terminal, and all others are 
understood as synonyms for the terminal name. All names but the 
last should be in lower case and contain no blanks; the last name 
may well contain upper case and blanks for readability. 

Terminal names (except for the last, verbose entry) should be 
chosen using the following conventions. The particular piece of 
hardware making up the terminal should have a root name chosen, 
thus "hp2621". This name should not contain hyphens, except 
that synonyms may be chosen that do not conflict with other 
names. Modes that the hardware can be in, or user preferences, 
should be indicated by appending a hyphen and an indicator of the 
mode. Thus, a vtlOO in 132 column mode would be vtlOO-w. 

The following suffixes should be used where possible: 

Suffix Meaning Example 

-w Wide mode (more than 80 columns) vt 1 - w 

-am With auto, margins (usually default) vt 1 -am 

-nam Without automatic margins vtlOO-nam 

-n Number of lines on the screen a a a - 6 

-n a No arrow keys (leave them in local) c 1 -n a 

-np Number of pages of memory c 1 - 4 p 

- r v Reverse video c 1 - r v 
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CAPABILITIES 

The variable is the name by which the programmer (at the ter- 
minf o level) accesses the capability. The capname is the short 
name used in the text of the database, and is used by a person up- 
dating the database. The i.code is the two letter internal code used 
in the compiled database, and always corresponds to the old 
termcap capability name. 

Capability names have no hard length limit, but an informal limit 
of 5 characters has been adopted to keep them short and to allow 
the tabs in the source file caps to line up nicely. Whenever pos- 
sible, names are chosen to be the same as or similar to the ANSI 
X3.64-1979 standard. Semantics are also intended to match those 
of the specification. 

(P) indicates that padding may be specified 

(G) indicates that the string is passed through tparm with parms 
as given (#/). 

(*) indicates that padding may be based on the number of lines 
affected 

(# .) indicates the zth parameter. 



Variable Booleans 


Capname 1. Code 


i Description 


auto_left_margin, 


bw 


bw 


cubl wraps from column to last 
column 


auto_right_margin, 


am 


am 


Terminal has automatic margins 


beehive__glitch, 


xsb 


xb 


Beehive (f l=escape, f2=ctrl C) 


ceol_standout_gliteh, 


xhp 


xs 


Standout not erased by overwriting 
(hp) 


eat_newline_glitch, 


xenl 


xn 


newline ignored after 80 cols 
(Concept) 


erase_overstrike, 


eo 


eo 


Can erase overstrikes with a blank 


generic_type, 


gn 


gn 


Generic line type (e.g.,, dialup, 
switch). 


hard_copy, 


he 


he 


Hardcopy terminal 


has_meta_key, 


km 


km 


Has a meta key (shift, sets parity 
bit) 


has_status_line, 


hs 


hs 


Has extra status line 


insert_null_glitch, 


in 


in 


Insert mode distinguishes nulls 


memory_above, 


da 


da 


Display may be retained above the 
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memory_below, 


db 


db 


move_insert_mode, 
move_standout_mode, 
overjstrike, 
status_line_esc_ok, 


mir 
msgr 

OS 

eslok 


mi 
ms 

OS 

es 


teleray_glitch, 


xt 


xt 


tilde_glitch, 

transparent_underline, 

xon_xoff, 


hz 
ul 
xon 


hz 
ul 
xo 


Numbers: 

columns, 
init_tabs, 
lines, 
lines_of_memory, 


cols 
it 

lines 
lm 


CO 

it 
li 
lm 


magic_cookie_glitch, 


xmc 


sg 


padding_baud_rate, 


pb 


pb 


virtual_terminal, 


vt 


vt 


width_status_line, 


wsl 


ws 


Strings: 
back tab, 
bell, 


cbt 
bel 


bt 
bl 


carriage_return, 
change_scroll_region, 


cr 
csr 


cr 
cs 


clear_all_tabs, 

clear_screen, 

clr_eol, 

clr_eos, 

column_address, 

command_character, 


tbc 

clear 

el 

ed 

hpa 

cmdch 


ct 
cl 
ce 
cd 
ch 
CC 



screen 

Display may be retained below the 

screen 

Safe to move while in insert mode 

Safe to move in standout modes 

Terminal overstrikes 

Escape can be used on the 

status line 

Tabs ruin, magic so char (Teleray 

1061) 

Hazeltine; can not print ~'s 

underline character overstrikes 

Terminal uses xon/xoff handshaking 



Number of columns in a line 

Tabs initially every # spaces 

Number of lines on screen or page 

Lines of memory if > lines. 

means varies 

Number of blank chars left by smso or 

rmso 

Lowest baud where cr/nl padding is 

needed 

Virtual terminal number 

(UNIX system) 

No. columns in status line 



Back tab (P) 

Audible signal (bell) (P) 

Carriage return (P*) 

change to lines #1 through #2 

(vtlOO) (PG) 

Clear all tab stops (P) 

Clear screen and home cursor (P*) 

Clear to end of line (P) 

Clear to end of display (P*) 

Set cursor column (PG) 

Term, settable cmd char in 
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cursor_address, 


cup 


cm 


cursor_down, 


cudl 


do 


cursor_home, 


home 


ho 


cursorjnvisible, 


civis 


vi 


cursor_left, 


cubl 


le 


cursor_mem_address, 


mrcup 


CM 


cursor_normal, 


cnorm 


ve 


cursor_right, 


cufl 


nd 


cuisor_to_.ll, 


11 


11 


cursor_up, 


cuul 


up 


cursor_visible, 


cvvis 


vs 


delete_character, 


dchl 


dc 


delete_line, 


dll 


dl 


dis_status_line, 


dsl 


ds 


down_half_line, 


hd 


hd 


enter_alt_charset_mode, 


, smacs 


as 


enter_blink_mode, 


blink 


mb 


enter_bold_mode, 


bold 


md 


enter_ca_mode, 


smcup 


ti 


enter_delete_mode, 


smdc 


dm 


enter_dim_mode, 


dim 


mh 


enter_insert_mode, 


smir 


im 


enter_protected_mode, 


prot 


mp 


enter_reverse_mode, 


rev 


mr 


enter_secure_mode, 


invis 


mk 


enter_standout_mode, 


smso 


so 


enter_underline_mode, 


smul 


us 


erase_chars 


ech 


ec 


exit_alt_charset_mode, 


rmacs 


ae 


exit_attribute_mode, 


sgrO 


me 


exit_ca_mode, 


rmcup 


te 


exit_delete_mode, 


rmdc 


ed 


exit_insert_mode, 


rmir 


ei 



prototype 

Screen rel. cursor motion row #1 

col#2(PG) 

Down one line 

Home cursor (if no cup) 

Make cursor invisible 

Move cursor left one space 

Memory relative cursor addressing 

Make cursor appear normal (undo 

vs/vi) 

Non-destructive space (cursor right) 

Last line, first column (if no cup) 

Upline (cursor up) 

Make cursor very visible 

Delete character (P*) 

Delete line (P*) 

Disable status line 

Half-line down (forward 

1/2 linefeed) 

Start alternate character set (P) 

Turn on blinking 

Turn on bold (extra bright) mode 

String to begin programs that use 

cup 

Delete mode (enter) 

Turn on half-bright mode 

Insert mode (enter); 

Turn on protected mode 

Turn on reverse video mode 

Turn on blank mode 

(chars invisible) 

Begin stand out mode 

Start underscore mode 

Erase #1 characters (PG) 

End alternate character set (P) 

Turn off all attributes 

String to end programs that use 

cup 

End delete mode 

End insert mode 
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exit_standout_mode, nnso se 

exit_underline_mode, rmul ue 

flash_screen, flash vb 

form_feed, ff ff 

from_status_line, fsl fs 

init_l string, isl il 

init_2string, is2 i2 

init_3string, is3 i3 

init_file, if if 

insert_character, ichl ic 

insertjine, ill al 

insert_padding, ip ip 

key_backspace, kbs kb 

key_catab, ktbc ka 

key_clear, kclr kC 

key_ctab, kctab kt 

key_dc, kdchl kD 

key_dl, kdll kL 

key_down, kcudl kd 

key_eic, krmir kM 

key_eol, kel kE 

key_eos, ked kS 

key_fO, kfO kO 

key_fl, kfl kl 

key_flO, kflO ka 

key_f2, kf2 k2 

key_f3, kf3 k3 

key_f4, kf4 k4 

key_f5, kf5 k5 

key_f6, kf6 k6 

key_f7, kf7 k7 

key_f8, kf8 k8 

key_f9, kf9 k9 

key_home, khome kh 

key_ic, kichl kl 

key_il, kill kA 

keyjeft, kcubl kl 



End stand out mode 

End underscore mode 

Visible bell (may not move cursor) 

Hardcopy terminal page eject (P*) 

Return from status line 

Terminal initialization string 

Terminal initialization string 

Terminal initialization string 

Name of file containing is 

Insert character (P) 

Add new blank line (P*) 

Insert pad after character 

inserted (p*) 

Sent by backspace key 

Sent by clear-all-tabs key 

Sent by clear screen or erase key 

Sent by clear-tab key 

Sent by delete character key 

Sent by delete line key 

Sent by terminal down arrow key 

Sent by rmir or smir in insert 

mode 

Sent by clear-to-end-of-line key 

Sent by clear-to-end-of-screen key 

Sent by function key fO 

Sent by function key f 1 

Sent by function key flO 

Sent by function key f2 

Sent by function key f3 

Sent by function key f4 

Sent by function key f5 

Sent by function key f6 

Sent by function key f7 

Sent by function key f8 

Sent by function key f9 

Sent by home key 

Sent by ins char/enter ins mode 

key 

Sent by insert line 

Sent by terminal left arrow key 
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keyjl, 


Idl 


kH 


Sent by home-down key 


key_npage, 


knp 


kN 


Sent by next-page key 


key_ppage, 


kpp 


kP 


Sent by previous-page key 


key_right, 


kcufl 


kr 


Sent by terminal right arrow key 


key_sf, 


kind 


kF 


Sent by scroll-forward/down key 


key_sr, 


kri 


kR 


Sent by scroll-backward/up key 


key_stab, 


khts 


kT 


Sent by set-tab key 


key_up, 


kcuul 


ku 


Sent by terminal up arrow key 


keypadjocal, 


rmkx 


ke 


Out of keypad transmit mode 


keypad_xmit, 


smkx 


ks 


Put terminal in keypad transmit 
mode 


lab fO, 


Iff) 


10 


Labels on funct key fO if not fO 


lab fl, 


lfl 


11 


Labels on funct key f 1 if not f 1 


lab flO, 


lflO 


la 


Labels on funct key flO if not flO 


lab f2, 


m 


12 


Labels on funct key f2 if not f2 


lab f3, 


lf3 


13 


Labels on funct key f3 if not f3 


lab f4, 


lf4 


14 


Labels on funct key f4 if not f4 


lab f5, 


lf5 


15 


Labels on funct key f5 if not f5 


lab f6, 


lf6 


16 


Labels on funct key f6 if not f6 


lab f7, 


in 


17 


Labels on funct key f7 if not f7 


lab f8, 


lf8 


18 


Labels on funct key f8 if not f8 


lab_f9, 


lf9 


19 


Labels on funct key f9 if not f9 


meta_on, 


smm 


mm 


Turn on meta mode (8th bit) 


meta_off, 


rmm 


mo 


Turn off meta mode 


newline, 


nel 


nw 


Newline (behaves like cr followed 
by If) 


pad_char, 


pad 


pc 


Pad character (rather than null) 


parm_dch, 


dch 


DC 


Delete #1 chars (PG*) 


parm_delete_line, 


dl 


DL 


Delete #1 lines (PG*) 


parm_down_cursor, 


cud 


DO 


Move cursor down #1 lines (PG*) 


parm_ich, 


ich 


IC 


Insert #1 blank chars (PG*) 


parmjndex, 


indn 


SF 


Scroll forward #1 lines (PG) 


parm_insert_line, 


il 


AL 


Add #1 new blank lines (PG*) 


parm_left_cursor, 


cub 


LE 


Move cursor left #1 spaces (PG) 


parm_right_cursor, 


cuf 


RI 


Move cursor right #1 spaces (PG*) 


parm_rindex, 


rin 


SR 


Scroll backward #1 lines (PG) 


parm_up_cursor, 


cuu 


UP 


Move cursor up #1 lines (PG*) 


pkey_key, 


pfkey 


pk 


Prog funct key #1 to type string 


pkey_local, 


pfloc 


Pi 


TrZ* 

Prog funct key #1 to execute 
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pkey_xmit, 

print_screen, 
prtr_off, 
prtr_on, 
repeat_char, 
reset_l string, 

reset_2string, 

reset_3string, 

reset_file, 

restore_cursor, 

row_address, 

save_cursor, 

scroll_forward, 

scroll_reverse, 

set_attributes, 

set_tab, 

set_window, 

tab, 

to_status_line, 
underline_char, 

up_half_line, 

init_prog, 

key_al, 

key_a3, 

key_b2, 

key_cl, 

key_c3, 



pfx 



px 



mcO 
mc4 
mc5 


ps 

pf 
po 


rep 
rsl 


rp 
rl 


rs2 


r2 


rs3 


r3 


rf 


rf 


re 


re 


vpa 


cv 


sc 


sc 


ind 


sf 


ri 


sr 


sgr 
hts 


sa 
st 


wind 


wi 


ht 


ta 


tsl 


ts 


uc 


uc 


hu 


hu 


iprog 
kal 


iP 
Kl 


ka3 


K3 


kb2 


K2 


kcl 


K4 


kc3 


K5 



string #2 

Prog funct key #1 to xmit 

string #2 

Print contents of the screen 

Turn off the printer 

Turn on the printer 

Repeat char #1 #2 times. (PG*) 

Reset terminal completely to 

sane modes. 

Reset terminal completely to 

sane modes. 

Reset terminal completely to 

sane modes. 

Name of file containing reset 

string 

Restore cursor to position of 

lastsc 

Vertical position absolute 

(set row) (PG) 

Save cursor position (P) 

Scroll text up (P) 

Scroll text down (P) 

Define the video attributes (PG9) 

Set a tab in all rows, 

current column 

Current window is lines #l-#2 

cols #3-#4 

Tab to next 8 space hardware 

tab stop 

Go to status line, column #1 

Underscore one char and move 

past it 

Half-line up (reverse 

1/2 linefeed) 

Path name of program for init 

Upper left of keypad 

Upper right of keypad 

Center of keypad 

Lower left of keypad 

Lower right of keypad 
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prtr_non, mc5p pO Turn on the printer for #1 bytes 

A Sample Entry 

The following entry, which describes the Concept- 100, is among 
the more complex entries in the terminf o file as of this writing. 

conceptlOO | cl00| concept | cl04 | cl00-4p | concept 100, 

am, bel=~G, blank=\EH, blink=\EC, clear=~L$<2*>, cnorm=\Ew, 

cols#80, cr="M$<9>, cubl="H, cudl=~J, cufl=\E=, 

cup=\Ea%pl%' '%+%c%p2%' '%+%c, 

cuul=\E;, cvvis=\EW, db, dchl=\E"A$<16*>, dim=\EE, dll=\E~B$<3*>, 

ed=\E~C$<16*>, el=\E~U$<16>, eo, flash=\Ek$<20>\EK, ht=\t$<8>, 

ill=\E~R$<3*>, in, ind="J, .ind=~J$<9>, ip=$<16*>, 

is2=\EU\Ef\E7\E5\E8\El\ENH\EK\E\200\Eo&\200\Eo\47\E, 

kbs="h, kcubl=\E>, kcudl=\E<, kcufl=\E=, kcuul=\E; , 

kfl=\E5, kf2=\E6, kf3=\E7, khome=\E?, 

lines#24, mir, pb#9600, prot=\EI, rep=\Er%pl%c%p2%' '%+%c$<.2*>, 

rev=\ED, rmcup=\Ev $<6>\Ep\r\n, rmir=\E\200, rmkx=\Ex, 

rmso=\Ed\Ee, rmul=\Eg, rmul=\Eg, sgr0=\EN\200, 

smcup=\EU\Ev 8p\Ep\r, smir=\E"P, smkx=\EX, smso=\EE\ED, 

smul=\EG, tabs, ul, vt#8, xenl, 

Entries may continue onto multiple lines by placing white space at 
the beginning of each line except the first. Comments may be in- 
cluded on lines beginning with "#". Capabilities in terminf o 
are of three types: Boolean capabilities which indicate that the 
terminal has some particular feature, numeric capabilities giving 
the size of the terminal or the size of particular delays, and string 
capabilities, which give a sequence which can be used to perform 
particular terminal operations. 

Types of Capabilities 

AH capabilities have names. For instance, the fact that the Con- 
cept has automatic margins (i.e., an automatic return and linefeed 
when the end of a line is reached) is indicated by the capability 
am. Hence the description of the Concept includes am. Numeric 
capabilities are followed by the character "#" and then the value. 
Thus cols, which indicates the number of columns the terminal 
has, gives the value "80" for the Concept. 

Finally, string valued capabilities, such as el (clear to end of line 
sequence) are given by the two-character code, an "=", and then 
a string ending at the next following ",". A delay in milliseconds 
may appear anywhere in such a capability, enclosed in $<..> 
brackets, as in el=\EK$<3>, and padding characters are sup- 
plied by tputs to provide this delay. The delay can be either a 
number, for example, "20," or a number followed by an "*", 
like "3*". A "*" indicates that the padding required is propor- 
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tional to the number of lines affected by the operation, and the 
amount given is the per-affected-unit padding required. (In the 
case of insert character, the factor is still the number of lines af- 
fected. This is always one unless the terminal has xenl and the 
software uses it.) When a "*" is specified, it is sometimes useful 
to give a delay of the form "3.5" to specify a delay per unit to 
tenths of milliseconds. (Only one decimal place is allowed.) 

A number of escape sequences are provided in the string valued 
capabilities for easy encoding of characters there. Both \E and 
\e map to an escape character, ~x maps to a Control-* for any 
appropriate x, and the sequences \n \1 \r \t \b \f \s 
give a newline, linefeed, return, tab, backspace, formfeed, and 
space. Other escapes include V for ", ^ for \ \, for comma, \: for :, 
and \0 for null. (\0 will produce \200, which does not terminate a 
string but behaves as a null character on most terminals.) Finally, 
characters may be given as three octal digits after a \. 

Sometimes individual capabilities must be commented out. To do 
this, put a period before the capability name. For example, see the 
second ind in the example above. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The 
most effective way to prepare a terminal description is by imitat- 
ing the description of a similar terminal in terminf o and to 
build up a description gradually, using partial descriptions with vi 
to check that they are correct. Be aware that a very unusual termi- 
nal may expose deficiencies in the ability of the terminf o file to 
describe it or bugs in vi. To test a new terminal description easi- 
ly, you may set the environment variable terminfo to a path- 
name of a directory containing the compiled description you are 
working on, and programs will look there, rather man in 
/usr/lib/terminf o. To get the padding for insert line right 
(if the terminal manufacturer did not document it), a severe test is 
to edit /etc/passwd at 9600 baud, delete 16 or so lines from 
the middle of the screen, then hit the "u" key several times quick- 
ly. If the terminal messes up, more padding is usually needed. A 
similar test can be used for insert character. 

Basic Capabilities 

The number of columns on each line for the terminal is given by 
the cols numeric capability. If the terminal is a CRT then the 
number of lines on the screen is given by the lines capability. 
If the terminal wraps around to the beginning of the next line 
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when it reaches the right margin, then it should have the am capa- 
bility. If the terminal can clear its screen, leaving the cursor in the 
home position, then this is given by the clear string capability. 
If the terminal overstrikes (rather than clearing a position when a 
character is struck over) then it should have the os capability. If 
the terminal is a printing terminal, with no soft copy unit, give it 
both he and os. (os applies to storage scope terminals, such as 
TEKTRONIX 4010 series, as well as hard copy and APL termi- 
nals.) If there is a code to move the cursor to the left edge of the 
current row, give this as cr. (Normally this will be carriage re- 
turn, Control-M.) If there is a code to produce an audible signal 
(bell, beep, etc) give this as bel. 

If there is a code to move the cursor one position to the left (such 
as backspace) that capability should be given as cub 1. Similarly, 
codes to move to the right, up, and down should be given as 
cuf 1, cuul, and cudl. These local cursor motions should not 
alter the text they pass over, for example, you would not normally 
use "cuf 1=" because the space would erase the character moved 
over. 

A very important point here is that the local cursor motions encod- 
ed in terminf o are undefined at the left and top edges of a CRT 
terminal. Programs should never attempt to backspace around the 
left edge, unless bw is given, and never attempt to go up locally 
off the top. In order to scroll text up, a program will go to the bot- 
tom left corner of the screen and send the ind (index) string. 

To scroll text down, a program goes to the top left corner of the 
screen and sends the ri (reverse index) string. The strings ind 
and ri are undefined when not on their respective corners of the 
screen. 

Parameterized versions of the scrolling sequences are indn and 
rin which have the same semantics as ind and ri except that 
they take one parameter, and scroll that many lines. They are also 
undefined except at the appropriate edge of the screen. 

The am capability tells whether the cursor sticks at the right edge 
of the screen when text is output, but this does not necessarily ap- 
ply to a cuf 1 from the last column. The only local motion which 
is defined from the left edge is if bw is given, then a cubl from 
the left edge will move to the right edge of the previous row. If 
bw is not given, the effect is undefined. This is useful for drawing 
a box around the edge of the screen, for example. If the terminal 
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has switch selectable automatic margins, the terminfo file usually 
assumes that this is on; i.e., am. If the terminal has a command 
which moves to the first column of the next line, that command 
can be given as nel (newline). It does not matter if the command 
clears the remainder of the current line, so if the terminal has no 
carriage return or linefeed, it may still be possible to craft a work- 
ing nel out of one or both of them. 

These capabilities suffice to describe hardcopy and "glass-tty" 
terminals. Thus the model 33 teletype is described as: 

33 | tty33 | tty | model 33 teletype, 

bel=~G, cols#72, cr=~M, cudl="J, he, ind="J, os, 

while the Lear Siegler ADM-3 is described as 

adm3 | 3 | lsi adm3, 

am, bel="G, clear=~Z, cols#80, cr=~M, cubl="H, 

cudl=~J, ind=*J, lines#24, 

Parameterized Strings 
Cursor addressing and other strings requiring parameters in the 
terminal are described by a parameterized string capability, with 
print f(3S) like escapes %x in it. For example, to address the 
cursor, the cup capability is given, using two parameters: the row 
and column to address to. (Rows and columns are numbered from 
zero and refer to the physical screen visible to the user, not to any 
unseen memory.) If the terminal has memory relative cursor ad- 
dressing, that can be indicated by mrcup. 

The parameter mechanism uses a stack and special % codes to 
manipulate it. Typically a sequence will push one of the parame- 
ters onto the stack and then print it in some format. Often more 
complex operations are necessary. 

The % encodings have the following meanings: 

%% outputs '%' 

%d print pop() as in printf 

%2d print pop() like %2d 

%3d print pop() like %3d 

%02d 

%03d as in printf 

%c print pop() gives %c 

%s print pop() gives %s 

%p[l-9] push ith parm 
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%P[a-z] set variable [a-z] to pop() 
%g[a-z] get variable [a-z] and push it 
%'c' char constant c 
%{nn} integer constant nn 

%+ %- %* %/ %m 

arithmetic (%m is mod): push(pop() op pop()) 
%& %| %~ bit operations: push (pop () op pop()) 
%= %> %< logical operations: push (pop () op pop()) 
%! %~ unary operations push (op pop()) 
%i add 1 to first two parms (for ANSI terminals) 

%? expr %t thenpart %e elsepart %; 

if-then-else, %e elsepart is optional. 

else-if's are possible ala Algol 68: 

%? ^ %t ^ %e c 2 %t b 2 %e c 3 %t b 3 %e c^ %t b 4 %e %; 

c. are conditions, b. are bodies. 

Binary operations are in postfix form with the operands in the usu- 
al order. That is, to get x-5 one would use "gx% { 5 } %-". 

Consider the HP2645, which, to get to row 3 and column 12, 
needs to be sent a \E&al2c03Y padded for 6 milliseconds. 
Note that the order of the rows and columns is inverted here, and 
that the row and column are printed as two digits. Thus its cup 

capability is "cup=6\E&%p2%2dc%pl%2dY". 

The Microterm ACT-IV needs the current row and column sent 
preceded by a " t, with the row and column simply encoded in 
binary, "cup=~T%pl%c%p2%c". Terminals which use "%c" 
need to be able to backspace the cursor (cubl), and to move the 
cursor up one line on the screen (cuul). This is necessary be- 
cause it is not always safe to transmit \n, ~D, and \r, as the 
system may change or discard them. (The library routines dealing 
with terminfo set tty modes so that tabs are never expanded, so \t 
is safe to send. This turns out to be essential for the Ann Arbor 
4080.) 

A final example is the LSI ADM-3a, which uses row and column 
offset by a blank character, thus "cup=\E=%pl%' 
' %+%c%p2%' ' %+%c". After sending "\E=", this pushes the 
first parameter, pushes the ASCII value for a space (32), adds 
them (pushing the sum on the stack in place of the two previous 
values) and outputs that value as a character. Then the same is 
done for the second parameter. More complex arithmetic is possi- 
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ble using the stack. 

If the terminal has row or column absolute cursor addressing, 
these can be given as single parameter capabilities hpa (horizon- 
tal position absolute) and vpa (vertical position absolute). Some- 
times these are shorter than the more general two parameter se- 
quence (as with the hp2645) and can be used in preference to 
cup. If there are parameterized local motions (e.g., move n 
spaces to the right) these can be given as cud, cub, cuf , and 
cuu with a single parameter indicating how many spaces to move. 
These are primarily useful if the terminal does not have cup, such 
as the TEKTRONIX 4025. 

Cursor Motions 

If the terminal has a fast way to home the cursor (to very upper 
left corner of screen) then this can be given as home; similarly a 
fast way of getting to the lower left-hand corner can be given as 
11; this may involve going up with cuul from the home position, 
but a program should never do this itself (unless 11 does) be- 
cause it can make no assumption about the effect of moving up 
from the home position. Note that the home position is the same 
as addressing to (0,0): to the top left corner of the screen, not of 
memory. (Thus, the \EH sequence on HP terminals cannot be 
used for home.) 

Area Clears 

If the terminal can clear from the current position to the end of the 
line, leaving the cursor where it is, this should be given as el. If 
the terminal can clear from the current position to the end of the 
display, then this should be given as ed. ed is only defined 
from die first column of a line. (Thus, it can be simulated by a re- 
quest to delete a large number of lines, if a true ed is not avail- 
able.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the 
cursor is, this should be given as ill; this is done only from the 
first position of a line. The cursor must then appear on the newly 
blank line. If the terminal can delete the line which the cursor is 
on, then this should be given as dll; this is done only from the 
first position on the line to be deleted. Versions of ill and dll 
which take a single parameter and insert or delete that many lines 
can be given as il and dl. If the terminal has a settable scrolling 
region (like the vtlOO) the command to set this can be described 
with the csr capability, which takes two parameters: the top and 
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bottom lines of the scrolling region. The cursor position is, alas, 
undefined after using this command. It is possible to get the effect 
of insert or delete line using this command - the sc and re (save 
and restore cursor) commands are also useful. Inserting lines at 
the top or bottom of the screen can also be done using ri or ind 
on many terminals without a true insert/delete line, and is often 
faster even on terminals with those features. 

If the terminal has the ability to define a window as part of 
memory, which all commands affect, it should be given as the 
parameterized string wind. The four parameters are the starting 
and ending lines in memory and the starting and ending columns 
in memory, in that order. 

If the terminal can retain display memory above, then the da ca- 
pability should be given; if display memory can be retained below, 
then db should be given. These indicate that deleting a line or 
scrolling may bring nonblank lines up from below or that scrolling 
back with ri may bring down nonblank lines. 

Insert/Delete Character 
There are two basic kinds of intelligent terminals with respect to 
insert/delete character which can be described using terminf o. 
The most common insert/delete character operations affect only 
the characters on the current line and shift characters off the end 
of the line rigidly. Other terminals, such as the Concept 100 and 
the Perkin Elmer Owl, make a distinction between typed and un- 
typed blanks on the screen, shifting upon an insert or delete only 
to an untyped blank on the screen which is either eliminated, or 
expanded to two untyped blanks. You can determine the kind of 
terminal you have by clearing the screen and then typing text 
separated by cursor motions. Type "abc def " using local 
cursor motions (not spaces) between the "abc" and the "def ". 
Then position the cursor before the "abc" and put the terminal in 
insert mode. If typing characters causes the rest of the line to shift 
rigidly and characters to fall off the end, then your terminal does 
not distinguish between blanks and untyped positions. If the 
"abc" shifts over to the "def" which then move together 
around the end of the current line and onto the next as you insert, 
you have the second type of terminal, and should give the capabil- 
ity in, which stands for "insert null". While these are two logi- 
cally separate attributes (one line vs. multiline insert mode, and 
special treatment of untyped spaces) we have seen no terminals 
whose insert mode cannot be described with the single attribute. 
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terminfo can describe both terminals which have an insert 
mode, and terminals which send a simple sequence to open a 
blank position on the current line. Give as smir the sequence to 
get into insert mode. Give as rmir the sequence to leave insert 
mode. Now give as ichl any sequence needed to be sent just 
before sending the character to be inserted. Most terminals with a 
true insert mode will not give ichl; terminals which send a se- 
quence to open a screen position should give it here. (If your ter- 
minal has both, insert mode is usually preferable to ichl. Do 
not give both unless the terminal actually requires both to be used 
in combination.) If post insert padding is needed, give this as a 
number of milliseconds in ip (a string option). Any other se- 
quence which may need to be sent after an insert of a single char- 
acter may also be given in ip. If your terminal needs both to be 
placed into an "insert mode" and a special code to precede each 
inserted character, then both smir/rmir and ichl can be given, 
and both will be used. The ich capability, with one parameter, n, 
will repeat the effects of ichl n times. 

It is occasionally necessary to move around while in insert mode 
to delete characters on the same line (e.g., if there is a tab after the 
insertion position). If your terminal allows motion while in insert 
mode you can give the capability mir to speed up inserting in 
this case. Omitting mir will affect only speed. Some terminals 
(notably Datamedia's) must not have mir because of the way 
their insert mode works. 

Finally, you can specify dchl to delete a single character, dch 
with one parameter, n, to delete ^characters, and delete mode by 
giving smdc and rmdc to enter and exit delete mode (any mode 
the terminal needs to be placed in for dchl to work). 

A command to erase n characters (equivalent to outputting n 
blanks without moving the cursor) can be given as ech with one 
parameter. 

Highlighting, Underlining, and Visible Bells 
If your terminal has one or more kinds of display attributes, these 
can be represented in a number of different ways. You should 
choose one display form as "standout mode", representing a 
good, high contrast, easy-on-the-eyes, format for highlighting er- 
ror messages and other attention getters. (If you have a choice, re- 
verse video plus half-bright is good, or reverse video alone.) The 
sequences to enter and exit standout mode are given as smso and 
rmso, respectively. If the code to change into or out of standout 
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mode leaves one or even two blank spaces on the screen, as the 
TVI 912 and Teleray 1061 do, then xmc should be given to tell 
how many spaces are left 

Codes to begin underlining and end underlining can be given as 
smul and rmul respectively. If the terminal has a code to 
underline the current character and move the cursor one space to 
the right, such as the Microterm Mime, this can be given as uc. 

Other capabilities to enter various highlighting modes include 
blink (blinking) bold (bold or extra bright) dim (dim or half- 
bright) invis (blanking or invisible text) prot (protected) rev 
(reverse video) sgrO (turn off all attribute modes) smacs (enter 
alternate character set mode) and rmacs (exit alternate character 
set mode). Turning on any of these modes singly may or may not 
turn off other modes. 

If there is a sequence to set arbitrary combinations of modes, this 
should be given as sgr (set attributes), taking 9 parameters. Each 
parameter is either or 1, as the corresponding attribute is on or 
off. The 9 parameters are, in order: standout, underline, reverse, 
blink, dim, bold, blank, protect, alternate character set. Not all 
modes need be supported by sgr, only those for which 
corresponding separate attribute commands exist. 

Terminals with the "magic cookie" glitch (xmc) deposit special 
"cookies" when they receive mode-setting sequences, which af- 
fect the display algorithm rather than having extra bits for each 
character. Some terminals, such as the HP 2621, automatically 
leave standout mode when they move to a new line or the cursor is 
addressed. Programs using standout mode should exit standout 
mode before moving the cursor or sending a newline, unless the 
msgr capability, asserting that it is safe to move in standout 
mode, is present 

If the terminal has a way of flashing the screen to indicate an error 
quietly (a bell replacement) then this can be given as flash; it 
must not move the cursor. 

If the cursor needs to be made more visible than normal when it is 
not on the bottom line (to make, for example, a non-blinking 
underline into an easier to find block or blinking underline) give 
this sequence as cwis. If there is a way to make the cursor 
completely invisible, give that as civis. The capability cnorm 
should be given which undoes the effects of both of these modes. 
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If the terminal needs to be in a special mode when running a pro- 
gram that uses these capabilities, the codes to enter and exit this 
mode can be given as smcup and rmcup. This arises, for ex- 
ample, from terminals like the Concept with more than one page 
of memory. If the terminal has only memory relative cursor ad- 
dressing and not screen relative cursor addressing, a one screen- 
sized window must be fixed into the terminal for cursor addressing 
to work properly. This is also used for the TEKTRONIX 4025, 
where smcup sets the command character to be the one used by 
terminf o. 

If your terminal correctly generates underlined characters (with no 
special codes needed) even though it does not overstrike, men you 
should give the capability ul. If overstrikes are erasable with a 
blank, then this should be indicated by giving eo. 

Keypad 

If the terminal has a keypad that transmits codes when the keys 
are pressed, this information can be given. Note that it is not pos- 
sible to handle terminals where the keypad only works in local 
(this applies, for example, to the unshifted HP 2621 keys). If the 
keypad can be set to transmit or not transmit, give these codes as 
smkx and rmkx. Otherwise the keypad is assumed to always 
transmit. The codes sent by the left arrow, right arrow, up arrow, 
down arrow, and home keys can be given as kcubl , kcuf 1 , 
kcuul, kcudl, and khome respectively. If there are func- 
tion keys such as fO, fl, . . ., flO, the codes they send can be given 
as kf 0, kfl, ..., kflO. If these keys have labels other than 
the default fO through flO, the labels can be given as lfO, 
If 1 , ..., If 1 0. The codes transmitted by certain other spe- 
cial keys can be given: kll (home down), kbs (backspace), 
ktbc (clear all tabs), kctab (clear the tab stop in this column), 
kclr (clear screen or erase key), kdchl (delete character), 
kdll (delete line), krmir (exit insert mode), kel (clear to end 
of line), ked (clear to end of screen), kichl (insert character or 
enter insert mode), kill (insert line), knp (next page), kpp (pre- 
vious page), kind (scroll forward/down), kri (scroll 
backward/up), khts (set a tab stop in this column). In addition, if 
the keypad has a 3 by 3 array of keys including the four arrow 
keys, the other five keys can be given as kal, ka3, kb2, kcl, 
and kc3. These keys are useful when the effects of a 3 by 3 
directional pad are needed. 
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Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the 
next tab stop can be given as ht (usually Control-I). A "back- 
tab" command which moves leftward to the next tab stop can be 
given as cbt. By convention, if the teletype modes indicate that 
tabs are being expanded by the computer rather than being sent to 
the terminal, programs should not use ht or cbt even if they are 
present, since the user may not have the tab stops properly set. If 
the terminal has hardware tabs which are initially set every n 
spaces when the terminal is powered up, the numeric parameter 
it is given, showing the number of spaces the tabs are set to. 
This is normally used by the tset command to determine wheth- 
er to set the mode for hardware tab expansion, and whether to set 
the tab stops. If the terminal has tab stops that can be saved in 
nonvolatile memory, the terminfo description can assume that they 
are properly set. 

Other capabilities include isl, is2, and is 3, initialization 
strings for the terminal, iprog, the path name of a program to be 
run to initialize the terminal, and if , the name of a file contain- 
ing long initialization strings. These strings are expected to set the 
terminal into modes consistent with the rest of the terminfo 
description. They are normally sent to the terminal, by the tset 
program, each time the user logs in. They will be printed in the 
following order isl; is2; setting tabs using tbc and hts; if; 
running the program iprog; and finally is3. Most initialization 
is done with is2. Special terminal modes can be set up without 
duplicating strings by putting the common sequences in is2 and 
special cases in isl and is 3. A pair of sequences that does a 
harder reset from a totally unknown state can be analogously 
given as rsl, rs2, rf, and rs3, analogous to is2 and if. 
These strings are output by the reset program, which is used 
when the terminal gets into a wedged state. Commands are nor- 
mally placed in rs2 and rf only if they produce annoying effects 
on the screen and are not necessary when logging in. For exam- 
ple, the command to set the vtlOO into 80-column mode would 
normally be part of is 2, but it causes an annoying glitch of the 
screen and is not normally needed since the terminal is usually al- 
ready in 80 column mode. 

If there are commands to set and clear tab stops, they can be given 
as tbc (clear all tab stops) and hts (set a tab stop in the current 
column of every row). If a more complex sequence is needed to 
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set the tabs than can be described by this, the sequence can be 
placed in is2 or if. 

Delays 

Certain capabilities control padding in the teletype driver. These 
are primarily needed by hard copy terminals, and are used by the 
tset program to set teletype modes appropriately. Delays embed- 
ded in the capabilities cr, ind, cubl, f f , and tab will cause 
the appropriate delay bits to be set in the teletype driver. If pb 
(padding baud rate) is given, these values can be ignored at baud 
rates below the value of pb. 

Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, 
then this can be given as pad. Only the first character of the 
pad string is used. 

If the terminal has an extra "status line" that is not normally used 
by software, this fact can be indicated. If the status line is viewed 
as an extra line below the bottom line, into which one can cursor 
address normally (such as the Heathkit hl9's 25th line, or the 24th 
line of a vtlOO which is set to a 23-line scrolling region), the capa- 
bility hs should be given. Special strings to go to the beginning 
of the status line and to return from the status line can be given as 
tsl and f si. (f si must leave the cursor position in the same 
place it was before tsl. If necessary, the sc and re strings can 
be included in tsl and f si to get this effect.) The parameter 
tsl takes one parameter, which is the column number of the 
status line the cursor is to be moved to. If escape sequences and 
other special commands, such as tab, work while in the status line, 
the flag eslok can be given. A string which turns off the status 
line (or otherwise erases its contents) should be given as dsl. If 
the terminal has commands to save and restore the position of the 
cursor, give them as sc and re. The status line is normally as- 
sumed to be the same width as the rest of the screen, e.g., cols. 
If the status line is a different width (possibly because the terminal 
does not allow an entire line to be loaded) the width, in columns, 
can be indicated with the numeric parameter wsl. 

If the terminal can move up or down half a line, this can be indi- 
cated with hu (half-line up) and hd (half-line down). This is pri- 
marily useful for superscripts and subscripts on hardcopy termi- 
nals. If a hardcopy terminal can eject to the next page (form 
feed), give this as f f (usually Control-L). 
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If there is a command to repeat a given character a given number 
of times (to save time transmitting a large number of identical 
characters) this can be indicated with the parameterized string 
rep. The first parameter is the character to be repeated and the 
second is the number of times to repeat it. Thus, 

tparm(repeat_char, ' x' , 10) 

is the same as "xxxxxxxxxx". 

If the terminal has a settable command character, such as the 
TEKTRONIX 4025, this can be indicated with cmdch. A proto- 
type command character is chosen which is used in all capabili- 
ties. This character is given in the cmdch capability to identify it. 
The following convention is supported on some UNIX systems: 
The environment is to be searched for a CC variable, and if found, 
all occurrences of the prototype character are replaced with the 
character in the environment variable. 

Terminal descriptions that do not represent a specific kind of 
known terminal, such as switch, dialup, patch, and net- 
work, should include the gn (generic) capability so that programs 
can complain that they do not know how to talk to the terminal. 
(This capability does not apply to virtual terminal descriptions for 
which the escape sequences are known.) 

If the terminal uses xon/xoff handshaking for flow control, give 
xon. Padding information should still be included so that routines 
can make better decisions about costs, but actual pad characters 
will not be transmitted. 

If the terminal has a "meta key" which acts as a shift key, setting 
the 8th bit of any character transmitted, this fact can be indicated 
with km. Otherwise, software will assume that the 8th bit is parity 
and it will usually be cleared. If strings exist to turn this "meta 
mode" on and off, they can be given as smm and rmm. 

If the terminal has more lines of memory than will fit on the 
screen at once, the number of lines of memory can be indicated 
with lm. A value of lm#0 indicates that the number of lines is not 
fixed, but that there is still more memory than fits on the screen. 

If the terminal is one of those supported by the UNIX virtual ter- 
minal protocol, the terminal number can be given as vt. 
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Media copy strings which control an auxiliary printer connected to 
the terminal can be given as mc : print the contents of the screen, 
mc4: turn off the printer, and mc5: turn on the printer. When the 
printer is on, all text sent to the terminal will be sent to the printer. 
It is undefined whether the text is also displayed on the terminal 
screen when the printer is on. A variation mc5p takes one param- 
eter, and leaves the printer on for as many characters as the value 
of the parameter, then turns the printer off. The parameter should 
not exceed 255. All text, including mc4, is transparently passed to 
the printer while an mc5p is in effect. 

Strings to program function keys can be given as pf key, pf loc, 
and pf x. Each of these strings takes two parameters: the function 
key number to program (from to 10) and the string to program it 
with. Function key numbers out of this range may program 
undefined keys in a terminal dependent manner. The difference 
between the capabilities is that pf key causes pressing the given 
key to be the same as the user typing the given string; pf loc 
causes the string to be executed by the terminal in local; and pf x 
causes the string to be transmitted to the computer. 

BUGS 

Hazeltine terminals, which do not allow tilde characters to be 
displayed should indicate hz. 

Terminals which ignore a linefeed immediately after an am wrap, 
such as the Concept and vtlOO, should indicate xenl. 

If el is required to get rid of standout (instead of merely writing 
normal text on top of it), xhp should be given. 

Teleray terminals, where tabs turn all characters moved over to 
blanks, should indicate xt (destructive tabs). This glitch is also 
taken to mean that it is not possible to position the cursor on top of 
a "magic cookie", that to erase standout mode it is instead neces- 
sary to use delete and insert line. 

The Beehive Superbee, which is unable to correctly transmit the 
escape or control-C characters, has xsb, indicating that the fl key 
is used for Escape and f2 for Control-C. (Only certain Super- 
bees have this problem, depending on the ROM.) 

Other specific terminal problems may be corrected by adding 
more capabilities of the form xx. 
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Similar Terminals 

If there are two very similar terminals, one can be defined as being 
just like the other with certain exceptions. The string capability 
use can be given with the name of the similar terminal. The 
capabilities given before use override those in the terminal type 
invoked by use. A capability can be cancelled by placing xx@ 
to the left of the capability definition, where xx is the capability. 
For example, the entry 

2621-nl, smkx@, rmkx@, use=2621, 

defines a 2621-nl that does not have the smkx or rmkx capabili- 
ties, and hence does not turn on the function key labels when in 
visual mode. This is useful for different modes for a terminal, or 
for different user preferences. 

FILES 

/usr/lib/terminfo/?/* files containing binary termi- 
nal descriptions 

SEE ALSO 

tic(lM), curses(3X), printf (3S), term(4). 
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NAME 

ttytype — database of terminal types by port 

DESCRIPTION 

ttytype is a database containing, for each tty port on the sys- 
tem, the kind of terminal that is attached to it. There is one line 
per port, containing the terminal kind (as a name listed in 
termcap(4)), a space, and the name of the tty, minus /dev/. 

This information is read by tset(l) and by login(l) to initial- 
ize the TERM environment variable at login time. 

EXAMPLES 

dw console 
3a ttyO 
hi 9 ttyl 
hi 9 tty2 
du ttydO 

FILES 

/etc/ttytype 

SEE ALSO 

tset(l), login(l). 



February, 1990 
Revision C 



tzfile(4) tzfile(4) 



NAME 

tzf ile — time-zone information 

SYNOPSIS 

tinclude <tzfile.h> 

DESCRIPTION 

The time-zone information files used by tzset(3) begin with 
bytes reserved for future use, followed by four 4-byte values of 
type long, written in a standard byte order where the high-order 
byte of the value is written first. These values are, in order: 

tzh_ttisstdcnt 

The number of standard/wall indicators stored in the file 

tzh_leapcnt 

The number of leap seconds for which data is stored in the 
file 

tzh_timecnt 

The number of "transition times" for which data is stored in 
the file 

tzh_typecnt 

The number of "local time types" for which data is stored in 
the file (must not be 0) 

tzh_charcnt 

The number of characters of "time-zone abbreviation 
strings" stored in the file 

The above header is followed by tzh_timecnt 4-byte values of 
type long, sorted in ascending order. These values are written in 
standard byte order. Each is used as a transition time (as returned 
by time(2)) where the rules for computing local time change. 
Next come tzh__timecnt 1-byte values of type unsigned 
char. Each one tells which of the different types of "local time" 
types described in the file is associated with the same-indexed 
transition time. These values serve as indices into an array of 
ttinf o structures that appears next in the file. These structures 
are defined as follows: 

struct ttinfo { 

long tt_gmtoff; 

int tt_isdst; 

unsigned inttt_abbrind; 
}; 



February, 1990 
Revision C 



tzfile(4) tzfile(4) 



Each structure is written as a 4-byte value for tt_gmtof f of 
type long, in a standard byte order, followed by a 1-byte value 
for tt_isdst and a 1-byte value for tt_abbrind. In each 
structure, tt_gmtof f gives the number of seconds to be added 
to Greenwich mean time (GMT), tt_isdst tells whether 
tm_isdst should be set by localtime(3), and tt_abbrind 
serves as an index into the array of time-zone abbreviation charac- 
ters that follow the ttinf o structure(s) in the file. 

Then there are tzh_leapcnt pairs of 4-byte values, written in a 
standard byte order. The first value of each pair gives the time (as 
returned by time(2)) at which a leap second occurs; the second 
gives the total number of leap seconds to be applied after the 
given time. The pairs of values are sorted in ascending order by 
time. 

Finally, there are tzh_ttisstdcnt standard/wall indicators, 
each stored as a 1-byte value. They tell whether the transition 
times associated with local time types are specified as standard 
time or wall-clock time and are used when a time-zone file is used 
in handling POSIX-style time-zone environment variables. 

local time uses the first standard-time ttinf o structure in the 
file (or simply the first ttinfo structure in the absence of a 
standard-time structure) if either tzh_timecnt is or the time 
argument is less than the first transition time recorded in the file. 

SEE ALSO 

ctime(3), tzic(lM), tzdump(lM). 
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NAME 

uf s — format of a UFS file-system volume 

SYNOPSIS 

#include <sys/types .h> 
#include <sys/time.h> 
#include <sys/vnode.h> 
#include <ufs/fs.h> 
#include <uf s/inode.h> 

DESCRIPTION 

Every Berkeley 4.2 file-system (UFS) storage volume (for exam- 
ple, a hard disk or a floppy disk) has a common format for certain 
vital information. Each volume is divided into a certain number 
of blocks. The block size is a parameter of the file system. Sec- 
tors to 7 on a file system may be used to contain bootstrap pro- 
grams. The first superblock for the file system is located at sector 
8. 

The actual file system begins at sector 16 with the first alternate 
superblock. The layout of the superblock as defined by the in- 
clude file <uf s / f s . h> is: 

#define FS_MAGIC 0x011954 
struct fs { 

struct fs *fs_link; 

/* linked list of file systems */ 
struct fs *fs_rlink; 

/* used for incore superblocks */ 
daddr_t fs_sblkno; 

/* addr of superblock in filesys */ 
daddr_t fs_cblkno; 

/* offset of cyl-block in filesys */ 
daddr_t fs_iblkno; 

/* offset of inode-blocks in filesys */ 
daddr_t fs_dblkno; 

/* offset of first data after eg */ 
long fs_cgof fset; 

/* cylinder group offset in cylinder */ 
long fs_cgmask; 

/* used to calc mod fs_ntrak */ 
time_t fs_time; 

/* last time written */ 
long fs_size; 

/* number of blocks in fs */ 
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long fs_dsize; 

/* number of data blocks in fs */ 
long fs_ncg; 

/* number of cylinder groups */ 
long fs_bsize; 

/* size of basic blocks in fs */ 
long fs_fsize; 

/* size of frag blocks in fs */ 
long fs_frag; 

/* number of frags in a block in fs */ 
/* these are configuration parameters */ 
long fs_minfree; 

/* minimum percentage of free blocks */ 
long fs_rotdelay; 

/* num of ms for optimal next block */ 
long fs_rps; 

/* disk revolutions per second */ 
/* these fields can be computed from the others */ 
long fs_bmask; 

/* ' 'blkoff" calc of blk offsets */ 
long fs_fmask; 

/* ' 'fragoff' calc of frag offsets */ 
long fs_bshift; 

/* ' Hblkno'' calc of logical blkno */ 
long f s_f shift ; 

/* ' 'numf rags' ' calc number of frags */ 
/* these are configuration parameters */ 
long fs_maxcontig; 

/* max number of contiguous blks */ 
long fs_maxbpg; 

/* max number of blks per cyl group */ 
/* these fields can be computed from the others */ 
long fs_fragshif't; 

/* block to frag shift */ 
long fs_fsbtodb; 

/* fsbtodb and dbtofsb shift constant */ 
long fs_sbsize; 

/* actual size of superblock */ 
long fs_csmask; 

/* csum block offset */ 
long fs_csshift; 

/* csum block number */ 
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long fs_nindir; 

/* value of NINDIR */ 
long fs_inopb; 

/* value of INOPB */ 
long fs_nspf; 

/* value of NSPF */ 
long fs_optlm; 

/* optimization preference */ 
long fs_sparecon[2] ; 

/* reserved for future constants */ 
long fs_state; 

/* file-system state */ 
long fs_id[2]; 

/* file-system id */ 
/* sizes determined by number of cylinder groups and their sizes */ 
daddr_t fs_csaddr; 

/* blk addr of cyl grp summary area */ 
long fs_cssize; 

/* size of cyl grp summary area */ 
long fs_cgsize; 

/* cylinder group size */ 
/* these fields should be derived from the hardware */ 
long fs_ntrak; 

/* tracks per cylinder */ 
long fs_nsect; 

/* sectors per track */ 
long fs_spc; 

/* sectors per cylinder */ 
/* this comes from the disk driver partitioning */ 
long fs_ncyl; 

/* cylinders in file system */ 
/* these fields can be computed from the others */ 
long fs_cpg; 

/* cylinders per group */ 
long fs_ipg; 

/* inodes per group */ 
long fs_fpg; 

/* blocks per group * fs_frag */ 
/* this data must be recomputed after crashes */ 
struct csum fs_cstotal; 

/* cylinder summary information */ 
/* these fields are cleared at mount time */ 
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char fs_fmod; 

/* superblock modified flag */ 
char fs_clean; 

/* file system is clean flag */ 
char fs_ronly; 

/* mounted read-only flag */ 
char fs_flags; 

/* currently unused flag */ 
char fs_fsmnt [MAXMNTLEN] ; 

/* name mounted on */ 
char f s_f sname [6] ; 

/* file-system name */ 
char fs_fpack[6]; 

/* file-system pack name */ 
/* these fields retain the current block allocation info */ 
long fs_cgrotor; 

/* last eg searched */ 
struct csum *fs_csp[MAXCSBUFS] ; 

/* list of fs_cs info buffers */ 
long fs_cpc; 

/* cyl per cycle in postbl */ 
short f s_postbl [MAXCPG] [NRPOS] ; 

/* head of blocks for each rotation */ 
long fs_magic; 

/* magic number */ 
u_char fs_rotbl[l]; 

/* list of blocks for each rotation */ 
/* actually longer */ 

}; 

A disk may contain one or more partitions. A disk partition may 
contain at most one file system. A file system consists of a 
number of cylinder groups. Each cylinder group has inodes and 
data. 

A BSD file system is described by its superblock, which in turn 
describes the cylinder groups. The superblock is critical data and 
is replicated in each cylinder group to protect against catastrophic 
loss. This is done at file-system creation time. In addition, the 
critical superblock data does not change, so the copies need not be 
referenced further unless disaster strikes. 
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Addresses stored in inodes are capable of addressing fragments of 
blocks. File-system blocks of at most size maxbsize can be op- 
tionally broken into 2, 4, or 8 pieces, each of which is addressable. 
These pieces may be dev_bsize or some multiple of a 

DEV_BSIZEunit. 

Large files consist of exclusively large data blocks. To avoid un- 
due wasted disk space, the last data block of a small file is allocat- 
ed as only as many fragments of a large block as are necessary. 
The file-system format retains only a single pointer to such a frag- 
ment, which is a piece of a single large block that has been divid- 
ed. The size of such a fragment can be determined from informa- 
tion in the inode by using theblksize(fs,ip, lbn) macro. 

The file system records space availability at the fragment level. 
To determine block availability, aligned fragments are examined. 

The root inode is the root of the file system. Inode can't be used 
for normal purposes and historically bad blocks were linked to 
inode 1, thus the root inode is 2. (Inode 1 is no longer used for 
this purpose; however, numerous dump tapes make this assump- 
tion, so we are forced to keep it.) The lost+f ound directory is 
given the next available inode when it is initially created by 
mkf s. 

f s_minf ree gives the minimum acceptable percentage of file 
system blocks that may be free. If the free list drops below this 
level, only the superuser may continue to allocate blocks. This 
may be set to if no reserve of free blocks is deemed necessary; 
however, severe performance degradations occur if the file-system 
is run at greater than 90% full. Thus the default value of 
f s_minf ree is 10%. 

Empirically, the best trade-off between block fragmentation and 
overall disk utilization at a loading of 90% comes with a fragmen- 
tation of 4; thus the default fragment size is a fourth of the block 
size. 

Cylinder-group Related Limits 

Each cylinder keeps track of the availability of blocks at different 
rotational positions so that sequential blocks can be laid out with 
minimum rotational latency. NRPOS is the number of rotational 
positions that are distinguished. With nrpos 8 the resolution of 
the summary information is 2 ms for a typical 3600 rpm drive. 
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f s_rotdelay gives the minimum number of milliseconds to in- 
itiate another disk transfer on the same cylinder. It is used in 
determining the rotationally optimal layout for disk blocks within 
a file. The default value for f s_rotdelay is 2 ms. 

Each file system has a statically allocated number of inodes. An 
inode is allocated for each nbpi bytes of disk space. The inode 
allocation strategy is extremely conservative. 

maxipg bounds the number of inodes per cylinder group and is 
needed only to keep the structure simpler by having the only a sin- 
gle variable size element (the free bit map). Note that maxipg 
must be a multiple of inopb( f s). 

MINBSIZE is the smallest allowable block size. With 
MINBSIZE of 4096, it is possible to create files of size 2*32 with 
only two levels of indirection. MINBSIZE must be big enough to 
hold a cylinder group block, so changes to (struct eg ) must 
keep its size within MINBSIZE. MAXCPG is limited only to di- 
mension an array in (struct eg); it can be made larger as long 
as that structure's size remains within the bounds dictated by 
MINBSIZE. Note that superblocks are never more than size 
SBSIZE. 

The pathname on which the file system is mounted is maintained 
in f s_f smnt. maxmntlen defines the amount of space allocat- 
ed in the superblock for this name. The limit on the amount of 
summary information per file system is defined by MAXCSBUFS. 
It is currently parameterized for a maximum of two million 
cylinders. 

Per cylinder-group information is summarized in blocks allocated 
from the data blocks of the first cylinder. These blocks are read in, 
from the location indicated by f s_csaddr, in addition to the su- 
perblock. The size of the summary information is given by 

f s_cssize. 

Note that sizeof (struct csum) must be a power of two in 
order for the f s_cs macro to work. 

Superblock for a File System 

maxbpc bounds the size of the rotational layout tables and is lim- 
ited by the fact that the superblock is of size SBSI ze. The size of 
these tables is inversely proportional to the block size of the file 
system. The size of the tables is increased when sector sizes are 
not powers of two, as this increases the number of cylinders in- 
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eluded before the rotational pattern repeats ( f s_cpc). The size 
of the rotational layout tables is derived from the number of bytes 
remaining in ( struct f s ) . 

maxbpg bounds the number of blocks of data per cylinder group 
and is limited by the fact that cylinder groups are at most one 
block. The size of the free-block table is derived from the size of 
blocks and the number of remaining bytes in the cylinder group 
structure (struct eg). 

Inode 

The inode is the focus of all file activity in the UNIX® file sys- 
tem. There is a unique inode allocated for each active file, each 
current directory, each mounted-on file, text file, and the root. An 
inode is named by its device/i-number pair. For further informa- 
tion, see the include file <uf s / inode . h>. 

SEE ALSO 

newf s(lM), svf s(4). 
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NAME 

utmp, wtmp 



utmp and wtmp entry formats 



SYNOPSIS 

#include <sys/types.h> 
#include <utmp.h> 

DESCRIPTION 

These files, which hold user and accounting information for such 
commands as who(l), write(l), and login(l), have the follow- 
ing structure as defined by <utmp . h>: 



#define UTMP_FILE 
# define WTMP_FILE 

#define ut name ut user 



"/etc/utmp" 
"/etc/wtmp" 



struct utmp { 












char 


ut_ 


user [8] ; 




/* 


User login name */ 


char 


ut_ 


~id[4]; 




/* 

* 


/etc/inittab id 
(usually line #) */ 


char 


ut_ 


_line[12]; 




/* 


device name (console, 
lnxx) */ 


short 


ut_ 


pid; 




/* 


process id */ 


short 


ut ~ 


_type; 




/* 


type of entry */ 


struct 


exit status 


{ 






short 


e termination; 


/* 


Process termination 












status */ 


sho: 


rt 


e exit; 




/* 


Process exit status * 


} ut exit; 






/* 


The exit status of 



time_t 
char 



ut_time; 
ut host [16] ; 



}; 



/* Definitions for ut type */ 



a process 
marked as 
DEAD_PROCESS */ 
time entry was made 
host name if remote 



# define 


EMPTY 







#define 


RUN LVL 


1 




#define 


BOOT TIME 


2 




#define 


OLD TIME 


3 




#define 


NEW_TIME 


4 




# define 


INIT_PROCESS 


5 


/ 


#define 


LOGIN_PROCESS 


6 


/ 


#define 


USER PROCESS 


7 


/ 


#define 


DEAD PROCESS 


8 




#define 


ACCOUNTING 


9 




#define 


UTMAXTYPE ACCOUNTING 


/ 



Process spawned 

by init */ 
A getty process 

waiting for login 
A user process */ 



Largest legal value 
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of ut_type */ 



/* Special strings or formats used in the ut_line 
/* field when accounting for something other than 
/* a process. No string for the ut_line field 
*/ can be more than 11 chars + a NULL in length. 
#define RUNLVL_MSG "run-level %c" 
#def ine BOOT_MSG "system boot" 
#define OTIME_MSG "old time" 
#defineNTIME MSG "new time" 



FILES 

/usr/include/utmp.h 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

login(l), who(l), write(l), getut(3C). 
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NAME 

ypf iles — the Yellow Pages database and directory structure 

DESCRIPTION 

The yellow pages (YP) network lookup service uses a database of 
dbm files in the directory hierarchy at /etc/yp. A dbm database 
consists of two files, created by calls to the dbm(3X) library pack- 
age. One has the filename extension . pag and the other has the 
filename extension .dir. For instance, the database named 
hst.nm, is implemented by a pair of files, hst.nm.pag and 
hst . nm. dir. A dbm database served by the YP is called a YP 
map. A YP domain is a named set of YP maps. Each YP domain 
is implemented as a subdirectory of /etc/yp containing the 
map. Any number of YP domains can exist. Each may contain 
any number of maps. 

No maps are required by the YP lookup service itself, although 
they may be required for the normal operation of other parts of the 
system. There is no list of maps which YP serves; if the map ex- 
ists in a given domain and a client asks about it, the YP will serve 
it. For a map to be accessible consistently, it must exist on all YP 
servers that serve the domain. To provide data consistency 
between the replicated maps, an entry to run ypxf r periodically 
should be made in /usr/lib/crontab on each server. More 
information on this topic is in ypxf r(lM). 

YP maps should contain two distinguished key-value pairs. The 
first is the key yp_last_modified, having as a value a ten- 
character ASCII order number. The order number should be the 
UNIX time in seconds when the map was built. The second key is 
YP_master_name, with the name of the YP master server as a 
value, makedbm generates both key-value pairs automatically. A 
map that does not contain both key-value pairs can be served by 
the YP, but the ypserv process will not be able to return values 
for "Get order number" or "Get master name" requests. In ad- 
dition, values of these two keys are used by ypxf r when it 
transfers a map from a master YP server to a slave. If ypxf r 
cannot figure out where to get the map or if it is unable to deter- 
mine whether the local copy is more recent than the copy at the 
master, you must set extra command line switches when you run 
it. 
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YP maps must be generated and modified only at the master 
server. They are copied to the slaves using ypxf r(lM) to avoid 
potential byte-ordering problems among YP servers running on 
machines with different architectures, and to minimize the amount 
of disk space required for the dbm files. The YP database can be 
initially set up for both masters and slaves by using ypinit(lM). 

After the server databases are set up, it is probable that the con- 
tents of some maps will change. In general, some ASCII source 
version of the database exists on the master, and it is changed with 
a standard text editor. The update is incorporated into the YP map 
and is propagated from the master to the slaves by running 
/etc/yp/Makefile. All vendor-supplied maps have entries 
in /etc/yp/Makefile; if you add a YP map, edit the this file 
to support the new map. The makefile uses makedbm to generate 
the YP map on the master, and yppush to propagate the changed 
map to the slaves, yppush is a client of the map ypservers, 
which lists all the YP servers. For more information on this topic, 
see yppush(lM). 

SEE ALSO 

makedbm(lM), ypinit(lM), ypmake(lM), ypxf r(lM), 
yppush(lM), yppoll(lM), ypserv(lM), rpcinf o(lM), 
A/UX Network Applications Programming, Appendix E: YP 
Protcol Specification. 
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NAME 

intro — introduction to miscellaneous facilities 

SYNOPSIS 

♦include <sys/socket .h> 
♦include <net/route.h> 
♦include <net/if.h> 

DESCRIPTION 

This section describes miscellaneous facilities (such as macro 
packages, character set tables, and so forth) and networking facili- 
ties (such as network protocols) available in the system. 

Macro packages, character set tables and hardware support for 
network interfaces are found among the standard Section 5 entries. 
Entries describing a protocol family are marked 5F, while entries 
describing protocol use are marked 5P. 

NETWORKING FACILITIES 
All network protocols are associated with a specific protocol fami- 
ly. A protocol family provides basic services to the protocol im- 
plementation to allow it to function within a specific network en- 
vironment. These services may include packet fragmentation and 
reassembly, routing, addressing, and basic transport. A protocol 
family may support multiple methods of addressing, though the 
current protocol implementations do not. A protocol family is 
normally comprised of a number of protocols, one per 
socket(2N) type. It is not required that a protocol family sup- 
port all socket types. A protocol family may contain multiple pro- 
tocols supporting the same socket abstraction. 

A protocol supports one of the socket abstractions detailed in 
socket (2N). A specific protocol may be accessed either by 
creating a socket of the appropriate type and protocol family, or 
by requesting the protocol explicitly when creating a socket. Pro- 
tocols normally accept only one type of address format, usually 
determined by the addressing structure inherent in the design of 
the protocol family/network architecture. Certain semantics of the 
basic socket abstractions are protocol specific. All protocols are 
expected to support the basic model for their particular socket 
type, but may, in addition, provide nonstandard facilities or exten- 
sions to a mechanism. For example, a protocol supporting the 
SOCK_STREAM abstraction may allow more than one byte of 
out-of-band data to be transmitted per out-of-band message. 
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A network interface is similar to a device interface. Network in- 
terfaces comprise the lowest layer of the networking subsystem, 
interacting with the actual transport hardware. An interface may 
support one or more protocol families or address formats. 

PROTOCOLS 

The system currently supports only the DARPA Internet protocols 
fully. Raw socket interfaces are provided to IP protocol layer of 
the DARPA Internet, to the IMP link layer (1822), and to Xerox 
PUP-1 layer operating on top of 3Mb/s Ethernet interfaces. Con- 
sult the appropriate manual pages in this section for more informa- 
tion regarding the support for each protocol family. 

ADDRESSING 

Associated with each protocol family is an address format. The 
following address formats are used by the system: 

#define AF_UNIX 1 /*local to host (pipes, portals)*/ 

#define AF_INET 2 /^internetwork: UDP, TCP, etc.*/ 

#define AF_IMPLINK 3 /*arpanet imp addresses*/ 

#define AF_PUP 4 /*pup protocols: e.g. BSP*/ 

Note: Only AF_INET is appropriate for this implementa- 
tion. 

ROUTING 

The network facilities provided limited packet routing. A simple 
set of data structures comprise a "routing table" used in selecting 
the appropriate network interface when transmitting packets. This 
table contains a single entry for each route to a specific network or 
host. A user process, the routing daemon, maintains this data base 
with the aid of two socket specific ioctl(2) commands, 
SIOCADDRT and SIOCDELRT. The commands allow the addi- 
tion and deletion of a single routing table entry, respectively. 
Routing table manipulations may only be carried out by superuser. 

A routing table entry has the following form, as defined in 
<net / route . h>; 

struct rtentry { 



u long 


rt hash; 


struct 


sockaddr rt dst; 


struct 


sockaddr rt gateway 


short 


rt flags; 


short 


rt refcnt; 


u long 


rt use; 


struct 


if net *rt ifp; 



}; 



February, 1990 

Revision C 



intro(5) intro(5) 



with rt_f lags defined from, 

#define RTF_UP Oxl /*route usable*/ 

#define RTF_GATEWAY 0x2 /^destination is a gateway*/ 

#define RTF_HOST 0x4 /*host entry (net otherwise)*/ 

Routing table entries come in three flavors: for a specific host, for 
all hosts on a specific network, for any destination not matched by 
entries of the first two types (a wildcard route). When the system 
is booted, each network interface autoconfigured installs a routing 
table entry when it wishes to have packets sent through it. Nor- 
mally the interface specifies the route through it is a * 'direct" con- 
nection to the destination host or network. If the route is direct, 
the transport layer of a protocol family usually requests the packet 
be sent to the same host specified in the packet. Otherwise, the in- 
terface may be requested to address the packet to an entity dif- 
ferent from the eventual recipient (that is, the packet is forward- 
ed). 

Routing table entries installed by a user process may not specify 
the hash, reference count, use, or interface fields; these are filled 
in by the routing routines. If a route is in use when it is deleted 
(rt_ref cnt is nonzero), the resources associated with it will not 
be reclaimed until further references to it are released. 

The routing code returns eexist if requested to duplicate an ex- 
isting entry, ESRCH if requested to delete a nonexistent entry, or 
enobufs if insufficient resources were available to install a new 
route. 

User processes read the routing tables through the /dev/kmem 
device. 

The rt_use field contains the number of packets sent along the 
route. This value is used to select among multiple routes to the 
same destination. When multiple routes to the same destination 
exist, the least-used route is selected. 

A wildcard routing entry is specified with a zero destination ad- 
dress value. Wildcard routes are used only when the system fails 
to find a route to the destination host and network. The combina- 
tion of wildcard routes and routing redirects can provide an 
economical mechanism for routing traffic. 
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INTERFACES 

Each network interface in a system corresponds to a path through 
which messages may be sent and received. A network interface 
usually has a hardware device associated with it, though certain 
interfaces such as the loopback interface, lo(5), do not. 

At boot time, each interface which has underlying hardware sup- 
port makes itself known to the system during the 
autoconfiguration process. Once the interface has acquired its ad- 
dress, it is expected to install a routing table entry so that mes- 
sages may be routed through it. Most interfaces require some part 
of their address specified with an siocsifaddr ioctl before 
they will allow traffic to flow through them. On interfaces where 
the network-link layer address mapping is static, only the network 
number is taken from the ioctl; the remainder is found in a 
hardware specific manner. On interfaces which provide dynamic 
network-link layer address mapping facilities (for example, 
lOMb/s Ethernets), the entire address specified in the ioctl is used. 

The following ioctl calls may be used to manipulate network 
interfaces. Unless specified otherwise, the request takes an 
if request structure as its parameter. This structure has the 
form 

#define ifr_addr ifr_ifru.if ru_addr /* address */ 
#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of 

p-to-p link */ 
#define ifr_flags if r_if ru. if ru_f lags /* flags */ 

struct ifreq { 

char if r_narae [16] ; /* name of. interface 

(e.g. "ecO") */ 
union { 

struct sockaddr ifru_addr; 
struct sockaddr if ru_dstaddr; 
short ifru_flags; 
} ifr ifru; 



SIOCSIFADDR Set interface address. Following the ad- 

dress assignment, the "initialization" 
routine for the interface is called. 

S I OCGI faddr Get interface address. 

S I OC S I FD S TADDR Set point to point address for interface. 

S I OCGI FD S TADDR Get point to point address for interface. 
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SIOCSIFFLAGS 



SIOCGIFFLAGS 
SIOCGIFCONF 



Set interface flags field. If the interface 
is marked down, any processes currently 
routing packets through the interface are 
notified. 

Get interface flags. 

Get interface configuration list. This re- 
quest takes an ifconf structure (see 
below) as a value-result parameter. The 
if c_len field should be initially set to 
the size of the buffer pointed to by 
if c_buf . On return it will contain the 
length, in bytes, of the configuration list. 



Structure used in SIOCGIFCONF request. 
Used to retrieve interface configuration 
for machine (useful for programs which 
must know all networks accessible) . 



*/ 

# define ifc_buf ifc_ifcu.ifcu_buf 
#define ifc req ifc_ifcu. ifcu_req 



struct ifconf { 
int 



ifc len; 



/* 



buffer address */ 
array of structures 
returned */ 



size of associated 
buffer */ 



union { 

caddr_t ifcu_buf; 

struct if req *ifcu_req; 
} ifc ifcu; 



}; 



SEE ALSO 

routed(lM), socket(2N), ioctl(2). 
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NAME 

ae — 3Com 10 Mb/s Ethernet interface 

DESCRIPTION 

The ae interface provides host access to an industry standard 10 
Mb/s Ethernet. 

The host's Internet address is specified at boot time with an 
SIOCSIFADDR ioctl. The hosts's Ethernet address is read 
from ROM on the Ethernet board using etheraddr(lM). The 
ae interface employs the address resolution protocol described in 
arp(5P) to dynamically map between Internet and Ethernet ad- 
dresses on the local network. 

DIAGNOSTICS 

ae%d: init failed 

The NIC chip on the Ethernet board would not initalize. 

ae%d transmitter frozen - resetting 

A packet transmission failed to complete within a predetermined 
timeout period. 

ae%d spurious interrupt 

An interrupt was received but no operation was active. 

ae%d: can't handle af%d 

The interface was handed a message with addresses formatted in 
an unsuitable address family; the packet was dropped. 

SEE ALSO 

etheraddr(lM), inet(5F), intro(5), arp(5P). 

FILES 

/etc/boot . d/ae6 
/etc/master . d/ae6 
/etc/startup.d/ae6 
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NAME 

arp — Address Resolution Protocol 

DESCRIPTION 

arp is a protocol used to dynamically map between DARPA In- 
ternet and lOMb/s Ethernet addresses on a local area network. It 
is used by all the lOMb/s Ethernet interface drivers and is not 
direcdy accessible to users. 

arp caches Internet-Ethernet address mappings. When an inter- 
face requests a mapping for an address not in the cache, arp 
queues the message which requires the mapping and broadcasts a 
message on the associated network requesting the address map- 
ping. If a response is provided, the new mapping is cached and 
any pending messages are transmitted, arp itself is not Internet 
or Ethernet specific; this implementation, however, is. arp will 
queue at most one packet while waiting for a mapping request to 
be responded to; only the most recently "transmitted" packet is 
kept. 

arp watches passively for hosts impersonating the local host (i.e. 
a host which responds to an arp mapping request for the local 
host's address) and will, optionally, periodically probe a network 
looking for impostors. 

DIAGNOSTICS 

"duplicate IP address!! sent from ethernet 
address: %x %x %x %x %x %x" 

arp has discovered another host on the local network which 
responds to mapping requests for its own Internet address. 
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NAME 

ascii — map of ASCII character set 

SYNOPSIS 

cat /usr/pub/ascii 

DESCRIPTION 

ascii is a map of the ASCII character set, giving both octal and 
hexadecimal equivalents of each character, to be printed as need- 
ed. It contains: 



000 nul 


001 


soh 


002 


stx 1003 


etx 


004 eot 


005 


enq 


006 ack 


007 bel 


010 bs 


011 


ht 


012 


nl 


1013 


vt 


014 np 


015 


cr 


016 so 


017 si 


020 die 


021 


del 


022 


dc 


2 1023 


dc3 


024 dc4 


025 


nak 


026 syn 


027 etb 


030 can 


031 


em 


032 


su 


b 1033 


esc 


034 fs 


035 


g s 


036 rs 


037 us 


040 sp 


041 


1 


042 


" 


1043 


# 


044 $ 


045 


% 


046 & 


047 ' 


050 ( 


051 


) 


052 


* 


1053 


+ 


054 , 


055 


- 


056 . 


057 / 


060 


061 


1 


062 


2 


1063 


3 


064 4 


065 


5 


066 6 


067 7 


070 8 


071 


9 


072 




1073 


; 


074 < 


075 


= 


076 > 


077 ? 


100 @ 


101 


A 


102 


B 


1103 


C 


104 D 


105 


E 


106 F 


107 G 


110 H 


111 


I 


112 


J 


1113 K 


114 L 


115 M 


116 N 


117 O 


120 P 


121 


Q 


122 


R 


1123 


s 


124 T 


125 


U 


126 V 


127 W 


130 X 


131 


Y 


132 Z 


1133 


[ 


134 \ 


135 


] 


136 ' 


137 _ 


140 ' 


141 


a 


142 


b 


1143 


c 


144 d 


145 


e 


146 f 


147 g 


150 h 


151 


i 


152 


J 


1153 


k 


154 1 


155 


m 


156 n 


157 o 


160 p 


161 


q 


162 


r 


1163 


s 


164 t 


165 


u 


166 v 


167 w 


170 x 


171 


y 


172 


z 


1173 


{ 


174 1 


175 


} 


176 " 


177 del 


00 nul 


01 


soh 


02 


stx 1 03 


etx 


04 eot 


05 


enq 


06 ack 


07 bel 


08 bs 


09 


ht 


0a 


nl 


1 0b 


vt 


0c np 


Od 


cr 


Oe so 


Of si 


10 die 


11 


del 


12 


dc 


21 13 


dc3 


14 dc4 


15 


nak 


16 syn 


17 etb 


18 can 


19 


em 


la 


subl lb 


esc 


lc fs 


Id 


g s 


le rs 


If us 


20 sp 


21 


! 


22 


" 


1 23 


# 


24 $ 


25 


% 


26 & 


27 • 


28 ( 


29 


) 


2a 


* 


1 2b 


+ 


2c , 


2d 


- 


2e . 


2f / 


30 


31 


1 


32 


2 


1 33 


3 


34 4 


35 


5 


36 6 


37 7 


38 8 


39 


9 


3a 




1 3b 


; 


3c < 


3d 


= 


3e > 


3f ? 


40 @ 


41 


A 


42 


B 


1 43 


C 


44 D 


45 


E 


46 F 


47 G 


48 H 


49 


I 


4a 


J 


1 4b K 


4c L 


4d M 


4e N 


4f O 


50 P 


51 


Q 


52 R 


1 53 


s 


54 T 


55 


U 


56 V 


57 W 


58 X 


59 


Y 


5a 


Z 


1 5b 


t 


5c \ 


5d 


] 


5e * 


5f _ 


60 ' 


61 


a 


62 


b 


1 63 


c 


64 d 


65 


e 


66 f 


67 g 


68 h 


69 


i 


6a 


J 


1 6b 


k 


6c 1 


6d 


m 


6e n 


6f o 


70 p 


71 


q 


72 


r 


1 73 


s 


74 t 


75 


u 


76 v 


77 w 


78 x 


79 


y 


7a 


z 


1 7b 


{ 


7c 1 


7d 


) 


7e " 


7f del 
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FILES 

/usr/pub/ascii 
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NAME 

environ — user environment 

SYNOPSIS 

extern char **environ; 

DESCRIPTION 

An array of strings called the environment is made available by 
exec(2) when a process begins. By convention these strings 
have the form " name=value" . The following names are used by 
various commands: 



PATH 



The sequence of directory prefixes that sh, time, 
nice(l), etc., apply in searching for a file known by 
an incomplete path name. The prefixes are separated 
by :. login(l) sets 

PATH=: /bin: /usr/bin 



HOME 



TERM 



A user's login directory, set by login(l) from the 
password file passwd(4). 

The kind of terminal for which output is to be 
prepared. This information is used by commands, 
such as nrof f , more, or vi, which may exploit 
special terminal capabilities. See /etc/termcap 
or (termcap(4)) for a list of terminal types. 

The file name of the user's login shell. 

The string describing the terminal in term, or the 
name of the termcap file, see termcap(4). 

A startup list of commands read by ex(l), edit(l), 
andvi(l). 

The login name of the user. 

Time zone information. The format is xxxnzzz 
where xxx is standard local time zone abbreviation, 
n is the difference is hours from GMT, and zzz is 
the abbreviation for the daylight-saving local time 
zone, if any; for example, EST5EDT. 

Further names may be placed in the environment by the export 
command and "name=value" arguments in sh(l), or by the 
setenv command if you use csh(l). Arguments may also be 
placed in the environment at the point of an exec(2). It is unwise 
to conflict with certain sh(l) variables that are frequently export- 



SHELL 
TERMCAP 

EXINIT 

LOGNAME 
TZ 
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edby .profile files: MAIL,PS1, PS2, IFS. 

SEE ALSO 

csh(l), ex(l), ksh(l), login(l), sh(l), exec(2), 
system(3S), termcap(4), tty(7). 
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NAME 

eqnchar — special character definitions for eqn and neqn 

SYNOPSIS 

eqn /usr/pub/eqnchar [options] [-] files] I trof f 
[options] 

eqn /usr/pub/cateqnchar [options] [-]files] \ trof f 
[options] 

neqn /usr/pub/eqnchar [options] [-]files] | trof f 
[options] 

eqn -Taps /usr/pub/apseqnchar [options] [-] files] 
I trof f [options] 

DESCRIPTION 

/usr/pub/eqnchar contains trof f(l) and nrof f (1) char- 
acter definitions for constructing characters that are not ordinarily 
available on a phototypesetter or printer. These definitions are 
primarily intended for use with eqn(l) and neqn(l). 

For a complete list of input and output characters contained in 
/usr/pub/eqnchar, see the "eqn Reference" in A/UX Text 
Processing Tools. 

/usr/pub/apseqnchar is a version of eqnchar tailored for 
the Autologic APS-5 phototypesetter. If you use apseqnchar, 
output will not look optimal on other phototypesetters. 
cat eqnchar is more "device independent," and should look 
reasonable on any device supported bytroff(l). You may link 
/usr/pub/eqnchar to /usr/pub/cateqnchar or to 
/usr/pub/apseqnchar. By default, /usr/pub/eqnchar 
is linked to /usr/pub/apseqnchar. 

FILES 

/usr/pub/eqnchar 

/usr/pub/apseqnchar 

/usr/pub/cateqnchar 

SEE ALSO 

eqn(l), neqn(l), trof f (1). 

"eqn Reference" in A/UX Text Processing Tools. 
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NAME 

f cntl — file control options 

SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

f cntl(2) provides for control over open files. The include file 
describes requests and arguments to f cntl(2) and open(2). 

#ifndef fcntl_h 

#define fcntl_h 

/* POSIX requires types; most applications don't do this yet! */ 

tifndef sys_types_h 

#include <sys/types.h> 
#endif /* ! sys_types_h */ 

/* Flag values accessible to open (2) and f cntl (2) */ 
/* (The first three can only be set by open) */ 
#if defined <_SYSV_SOURCE) || defined (_POSIX_SOURCE) 

#ifndef sys_file_h 

#define 0_RDONLY 

# define 0_WRONLY 1 

# define 0_RDWR 2 

#define 0_APPEND 010 /* append (writes 

guaranteed at the end) */ 

/* Flag values accessible only to open (2) */ 
#define 0_CREAT 00400 /* open with file create 

(uses third open arg) */ 
#define 0_TRUNC 01000 /* open with truncation */ 
#define 0_EXCL 02000 /* exclusive open */ 

/* fcntl (2) requests */ 

#define F_DUPFD /* Duplicate fildes */ 

#define F_GETFD 1 /* Get fildes flags */ 

#def ine F_SETFD 2 /* Set fildes flags */ 

#define F_GETFL 3 /* Get file flags */ 

#def ine F_SETFL 4 /* Set file flags */ 

#def ine F_GETLK 5 /* Get file lock */ 

#define F_SETLK 6 /* Set file lock */ 

#define F_SETLKW 7 /* Set file lock and wait */ 

/* file segment locking set data type - information passed */ 
/* to system by user */ 
struct flock { 

short l_type; 

short l_whence; 

long l_start; 

long 1 len; /* len = means until end of file */ 
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int l_pid; 
}; 

/* file segment locking types */ 
#define F_RDLCK 01 /* Read lock */ 
#def ine F_WRLCK 02 /* Write lock */ 
#define F_UNLCK 03 /* Remove locks */ 

#endif /* _SYSV_SOURCE | | _POSIX_SOURCE */ 

#ifdef _BSD_SOURCE 

/* Additional fcntl(2) request */ 

#define F_GETOWN 8 /* Get owner */ 

#define F_SETOWN 9 /* Set owner */ 

#endif /* _BSD_SOURCE */ 

#ifdef _POSIX_SOURCE 

/* File access mode mask */ 

#define 0_ACCMODE 03 

/* POSIX-defined argument to F_SETFD */ 
#define FD_CLOEXEC 0x0001 

/* POSIX-defined flag values accesible to open (2) and/or fcntl(2) */ 
#define 0_NONBLOCK 040000 /* 0_NDELAY POSIX style */ 
#define 0_NOCTTY 0100000 /* don't assign controlling tty */ 
#endif /* _POSIX_SOURCE */ 

#ifdef _AUX_SOURCE 

/* Implementation-define flag values accessible to open (2) */ 

#define 0_GETCTTY 0200000 /* force controlling tty assignment */ 

#endif /* _AUX_SOURCE */ 

#endif /* ! fcntl h */ 



SEE ALSO 

f cntl(2), open(2). 
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NAME 

font 



description files for device-independent trof f 



SYNOPSIS 

trof f -Ttty-type ... 

DESCRIPTION 

For each phototypesetter that trof f (1) supports and that is avail- 
able on your system, there is a directory containing files describ- 
ing the device and its fonts. This directory is named 
/usr/lib/f ont / dev tty-type where tty-type is the name of the 
phototypesetter. Currently, the supported devices are aps for the 
Autologic APS-5, psc for a PostScript® device such as the 
Apple LaserWriter®, and iw for the Apple ImageWriter® II. 

For a particular phototypesetter, tty-type, the ASCII file DESC in 
the directory /usr/lib/font/devtfv-ry/?e describes its 
characteristics. A binary version of the file (described later in this 
section) is found in the file /usr/lib/font/devtfv- 
typel DESC . out. Each line of this ASCII file starts with a word 
that identifies the characteristic which is followed by appropriate 
specifiers. Blank lines and lines beginning with the # character 
are ignored. 

The legal lines for DESC are: 



res num. 

hor num 
vert num. 
unitwidth num 
sizescale num 
paperwidth num 
paperlength num 
biggestfont num 
sizes num num ... 

fonts num name .. 



Resolution of device in basic increments 
per inch. 

Smallest unit of horizontal motion. 

Smallest unit of vertical motion. 

Point size in which widths are specified. 

Scaling for fractional point sizes. 

Width of paper in basic increments. 

Length of paper in basic increments. 

Maximum size of a font. 

List of point sizes available on the 
typesetter. 

Number of initial fonts followed by the 
names of the fonts. For example 

fonts 4 R I B S 
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char set This always comes last in the file and is 

on a line by itself. Following it is the list 
of special character names for this dev- 
ice. Names are separated by a space or a 
newline. The list can be as long as 
necessary. Names not in this list are not 
allowed in the font description files. 

res is the basic resolution of the device in increments per inch. 
hor and vert describe the relationships between motions in the 
horizontal and vertical directions. If the device is capable of mov- 
ing in single basic increments in both directions, both hor and 
vert would have values of 1. If the vertical motions only take 
place in multiples of two basic units while the horizontal motions 
take place in the basic increments, then hor would be 1, while 
vert would be 2. unitwidth is the point size in which all 
width tables in the font description files are given, trof f au- 
tomatically scales the widths from the unitwidth size to the 
point size it is working with, sizescale is not currently used 
and is 1. paperwidth is the width of the paper in basic incre- 
ments. The APS-5 is 6120 increments wide, paperlength is 
the length of a sheet of paper in the basic increments, bi gge s t - 
font is the maximum number of characters on a font. 

For each font supported by the phototypesetter, there is also an 
ASCII file with the same name as the font (for example, R, I, cw). 
The format for a font description file is 

name name Name of the font, such as R or cw. 

internalname name 

Internal name of the font. 

special Sets a flag indicating that the font is spe- 

cial. 

ligatures name...O 

Sets a flag indicating font has ligatures. 
The list of ligatures follows and is ter- 
minated by a zero. Accepted ligatures 
are: ff, fi, fl, f fi,and ffl. 

spacewidth num Specifies width of space if something 
other than default (1/3 of em) is desired. 

charset The charset must come at the end. 

Each line following the word charset 
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describes one character in the font. Each 
line has one of two formats: 

name width kerning code 
name " 

where name is either a single ASCII 
character or a special character name 
from the list found in DESC. The width 
is in basic increments. The kerning in- 
formation is 1 if the character descends 
below the line, 2 if it rises above the 
letter "a," and 3 if it both rises and des- 
cends. The kerning information for spe- 
cial characters is not used and so may be 
0. The code is the number sent to the 
typesetter to produce the character. The 
second format is used to indicate that the 
character has more than one name. The 
double quote indicates that this name has 
the same values as the preceding line. 
The kerning and code fields are not used 
if the width field is a double quote char- 
acter. The total number of different char- 
acters in this list should not be greater 
than the value of biggest font in the 
DESC file (as described earlier). 

trof f and its postprocessors read this information from binary 
files produced from the ASCII files by a program distributed with 
trof f called makedev. For those with a need to know, a 
description of the format of these files follows. 

The file DESC. out starts with the dev structure, defined by 
dev . h. 

/* 

dev.h: characteristics of a typesetter 
*/ 



/* number of bytes in file, */ 

/* excluding dev part */ 

/* basic resolution in goobies 

per inch */ 
/* goobies horizontally */ 



struct 


dev { 


short 


f ilesize; 


short 


res; 


short 


hor; 


short 


ve rt ; 
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short 


unitwidth; 


/* 


size at which widths 
are given*/ 


short 


nf onts; 


/* 


number fonts physically 
available */ 


short 


nsizes; 


/* 


number of pointsizes */ 


short 


sizescale; 


/* 


scaling for fractional 
point sizes */ 


short 


paperwidth; 


/* 


max line length in units */ 


short 


paperlength; 


/* 


max paper length in units */ 


short 


nchtab; 


/* 


number of funny names 
in chtab */ 


short 


lchname; 


/* 


length of chname table */ 


short 


biggestfont; 


/* 


max # of chars in a font */ 


short 

}; 


spare2; 


/* 


in case of expansion */ 



filesize is merely the size of everything in DESC.out ex- 
cluding the dev structure, nfonts is the number of different 
font positions available, nsizes is the number of different point 
sizes supported by this typesetter, nchtab is the number of spe- 
cial character names, lchname is the total number of characters, 
including nulls, needed to list all the special character names. At 
the end of the structure are two spares for later expansion. 

Immediately following the dev structure are a number of tables. 
First is the sizes table, which contains nsizes+1 shorts (a null 
at the end), describing the point sizes of text available on this dev- 
ice. The second table is the f unny_char_index_table. It 
contains indexes for the the table which follows it, the 
f unny_char_st rings. The indexes point to the beginning of 
each special character name which is stored in the 
funny_char_st rings table. The funny_char_strings 
table is lchname characters long, while the 
f unny_char_index_table is nchtab shorts long. 

Following the dev structure will occur nfonts {font}. out files, 
which are used to initialize the font positions. These {font}. out 
files, which also exist as separate files, begin with a font struc- 
ture and then are followed by four character arrays. 

struct Font { /* characteristics of a font */ 
char nwfont; /* number of width entries */ 
char specfont; /* 1 == special font */ 
char ligfont; /* 1 == ligatures exist 

on this font */ 
char name font [10] ; /* name of this font, 

e.g., R */ 
char intname [10] ; /* internal name of font, 

in ASCII */ 
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The font structure tells how many defined characters there are in 
the font, whether the font is a "special" font and if it contains 
ligatures. It also has the ASCII name of the font, which should 
match the name of the file it appears in, and the internal name of 
the font located on the typesetting device (intname). The internal 
name is independent of the font position and name that trof f 
knows about. For example, you might say "mount R in position 
4", but when asking the typesetter to actually produce a character 
from the R font, the postprocessor which instructs the typesetter 
would use intname. 

The first three character arrays are specific for the font and run in 
parallel. The first array, widths, contains the width of each 
character relative to unitwidth. unitwidth is defined in 
DESC. The second array, kerning, contains kerning informa- 
tion. If a character rises above the letter "a," 02 is set. If it des- 
cends below the line, 01 is set. The third array, codes, contains 
the code that is sent to the typesetter to produce the character. 

The fourth array is defined by the device description in DESC. It 
is the f ont_index_table. This table contains indices into the 
width, kerning, and code tables for each character. The ord- 
er that characters appear in these three tables is arbitrary and 
changes from one font to the next. In order for trof f to be able 
to translate from ASCII and the special character names to these 
arbitrary tables, the font_index_table is created with an 
order which is constant for each device. The number of entries in 
this table is 96 plus the number of special character names for this 
device. The value 96 is 128-32, the number of printable charac- 
ters in the ASCII alphabet. To determine whether a normal ASCII 
character exists, trof f takes the ASCII value of the character, 
subtracts 32, and looks in the f ont_index_table. If it finds a 
0, the character is not defined in this font. If it finds anything else, 
that is the index into widths, kerning, and codes tables that 
describe the character. 

To look up a special character name, (for example \ (pi, the 
mathematical plus sign), and to determine whether it appears in a 
particular font or not, the following procedure is followed. A 
counter is set to and an index to a special character name is 
picked out of the counter position in the 
funny_char_index_table. A string comparison is per- 
formed between the element in the array 
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funny_char_st rings [funny_char_index_table 
[counter]] and the special character name, in our example pi, and 
if it matches, then trof f refers to this character as (96+counter). 
When it wants to determine whether a specific font supports this 
character, it looks in f ont_index_table [ (96+counter) ] , to 
see whether there is a 0, meaning the character does not appear in 
this font, or number, which is the index into the widths, kern- 
ing, and codes tables. 

Notice that since a value of in the f ont_index_table indi- 
cates that a character does not exist, the 0th element of the 
width, kerning, and codes arrays are not used. For this rea- 
son the 0th element of the width array can be used for a special 
purpose, defining the width of a space for a font. Normally a 
space is defined by trof f to be 1/3 of the width of the \ (em 
character, but if the 0th element of the width array is nonzero, 
then that value is used for the width of a space. 

SEE ALSO 

troff(l). 

FILES 

/usr/lib/font/devtfy_ry/WDESC.out 
/usr/lib/font/devfO>-O'/?e//0nf.out 
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NAME 

greek — graphics for the extended TTY-37 type-box 

SYNOPSIS 

cat /usr/pub/greek [ I greek -^terminal ] 

DESCRIPTION 

greek gives the mapping from ASCII to the "shift-out" graphics 
in effect between SO and Si on TELETYPE Model 37 terminals 
equipped with a 128-character type-box. These are the default 
greek characters produced by nrof f . The filters of greek(l) at- 
tempt to print them on various other terminals. The file contains: 



alpha 


a 


A 


beta 


P 


B 


gamma 


Y 


\ 


GAMMA 


r 


G 


delta 


5 


D 


DELTA 


A 


W 


epsilon 


e 


S 


zeta 


C 


Q 


eta 


Tl 


N 


THETA 


e 


T 


theta 


e 


o 


lambda 


X 


L 


LAMBDA 


A 


E 


mu 


v- 


M 


nu 


V 


@ 


xi 


% 


X 


Pi 


7t 


J 


PI 


n 


P 


rho 


p 


K 


sigma 


a 


Y 


SIGMA 


i 


R 


tau 


X 


I 


phi 


<t> 


U 


PHI 


<D 


F 


psi 


V 


V 


PSI 


¥ 


H 


omega 


(0 


C 


OMEGA 


Q 


Z 


nabla 


V 


[ 


not 


— i 




partial 


d 


1 


integral 


J 


" 








FILES 


















/usr/pub/greek 














SEE ALSO 



















300(1), 4014(1), 450(1), greek(l), nroff(l), tc(l). 
"Other Text Processing Tools" in AIUX Text Processing Tools. 
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NAME 

icmp — Internet Control Message Protocol 

SYNOPSIS 

None; included automatically with inet(5F). 

DESCRIPTION 

The Internet Control Message Protocol, ICMP, is used by gate- 
ways and destination hosts which process datagrams to communi- 
cate errors in datagram-processing to source hosts. The datagram 
level of Internet is discussed in ip(5P). ICMP uses the basic sup- 
port of IP as if it were a higher level protocol; however, ICMP is 
actually an integral part of IP. ICMP messages are sent in several 
situations; for example: when a datagram cannot reach its destina- 
tion, when the gateway does not have the buffering capacity to 
forward a datagram, and when the gateway can direct the host to 
send traffic on a shorter route. 

The Internet protocol is not designed to be absolutely reliable. 
The purpose of these control messages is to provide feedback 
about problems in the communication environment, not to make 
IP reliable. There are still no guarantees that a datagram will be 
delivered or that a control message will be returned. Some da- 
tagrams may still be undelivered without any report of their loss. 
The higher level protocols which use IP must implement their own 
reliability mechanisms if reliable communication is required. 

The ICMP messages typically report errors in the processing of 
datagrams; for fragmented datagrams, ICMP messages are sent 
only about errors in handling fragment of the datagram. To 
avoid the infinite regress of messages about messages etc., no 
ICMP messages are sent about ICMP messages. ICMP may how- 
ever be sent in response to ICMP messages (for example, 
ECHOREPLY). There are eleven types of ICMP packets which 
can be received by the system. They are defined in this excerpt 
from <netinet/ip_icmp.h>, which also defines the values 
of some additional codes specifying the cause of certain errors. 
(Comments have been stripped for this listing.) 

/* 

* Definition of type and code field values 

*/ 
#define ICMP_ECHOREPLY 
#define ICMPJJNREACH 3 

# define ICMP UNREACH NET 
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♦define ICMP_UNREACH_HOST 1 

#define ICMP_UNREACH_PROTOCOL 2 

#define ICMP_UNREACH_PORT 3 
♦define ICMP_UNREACH_NEEDFRAG 4 
♦define ICMP_UNREACH_SRCFAIL 5 

♦define ICMP_SOURCEQUENCH 4 

♦define ICMP_REDIRECT 5 

♦define ICMP_REDIRECT_NET 
♦define ICMP_REDIRECT_HOST 1 
♦define ICMP_REDIRECT_TOSNET 2 
♦define ICMP_REDIRECT_TOSHOST 3 

♦define ICMP_ECHO 8 

♦define ICMP_TIMXCEED 11 

♦define ICMP_TIMXCEED_INTRANS 
♦define ICMP_TIMXCEED_REASS 1 

♦define ICMP_PARAMPROB 12 

♦define ICMP_TSTAMP 13 

♦define I CMP_T STAMP REPLY 14 

♦define ICMP_IREQ 15 

♦define ICMP_IREQREPLY 16 

Arriving ECHO and TSTAMP packets cause the system to gen- 
erate ECHOREPLY and TSTAMPREPLY packets. IREQ packets 
are not yet processed by the system, and are discarded. UN- 
REACH, SOURCEQUENCH, TIMXCEED and PARAMPROB 
packets are processed internally by the protocols implemented in 
the system, or reflected to the user if a raw socket is being used; 
see ip(5P). REDIRECT, ECHOREPLY, TSTAMPREPLY and 
IREQREPLY are also reflected to users of raw sockets. In addi- 
tion, REDIRECT messages cause the kernel routing tables to be 
updated; see routing(5N). 

SEE ALSO 

inet(5F), ip(5P). 

Internet Control Message Protocol, RFC792, J. Postel, USC-ISI 

BUGS 

IREQ messages are not processed properly: the address fields are 
not set. 

Messages which are source routed are not sent back using inverted 
source routes, but rather go back through the normal routing 
mechanisms. 
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NAME 

inet — Internet protocol family 

SYNOPSIS 

♦include <sys/types .h> 
♦include <netinet/in.h> 

DESCRIPTION 

The Internet protocol family is a collection of protocols layered 
atop the Internet Protocol (IP) transport layer, and utilizing the In- 
ternet address format. The Internet family provides protocol sup- 
port for the SOCK_STREAM, SOCK_DGRAM, and SOCK_RAW 
socket types; the SOCK_raw interface provides access to the IP 
protocol. 

ADDRESSING 

Internet addresses are four byte quantities, stored in network stan- 
dard format (on the VAX these are word and byte reversed). The 
include file <netinet/in . h> defines this address as a discrim- 
inated union. 

Sockets bound to the Internet protocol family utilize the following 
addressing structure, 

struct sockaddr_in { 

short sin_family; 
u_short sin_port; 
struct in_addr sin_addr; 
char sin_zero[8] ; 

}; 

Sockets may be created with the address inaddr_any to effect 
"wildcard" matching on incoming messages. 

PROTOCOLS 

The Internet protocol family is comprised of the IP transport pro- 
tocol, Internet Control Message Protocol (ICMP), Transmission 
Control Protocol (TCP), and User Datagram Protocol (UDP). 
TCP is used to support the SOCK_STREAM abstraction while UDP 
is used to support the SOCK_dgram abstraction. A raw interface 
to IP is available by creating an Internet socket of type 
SOCK_raw. The ICMP message protocol is not directly accessi- 
ble. 
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SEE ALSO 

tcp(5P), udp(5P), ip(5P). 

CAVEAT 

The Internet protocol support is subject to change as the Internet 
protocols develop. Users should not depend on details of the 
current implementation, but rather the services exported. 
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NAME 

ip — Internet Protocol 

SYNOPSIS 

♦include <sys/socket .h> 
♦include <netinet/in.h> 

DESCRIPTION 

IP is the transport layer protocol used by the Internet protocol 
family. It may be accessed through a "raw socket" when 
developing new protocols, or special purpose applications. IP 
sockets are connectionless, and are normally used with the send- 
to and recvf rom calls, though the connect(2N) call may also 
be used to fix the destination for future packets (in which case the 
read(2) or recv(2N) and write(2) or send(2N) system calls 
may be used). 

Outgoing packets automatically have an IP header prefixed to 
them (based on the destination address and the protocol number 
the socket is created with). Likewise, incoming packets have their 
IP header stripped before being sent to the user. 

ERRORS 

A socket operation may fail with one of the following errors re- 
turned: 

[EISCONN] when trying to establish a connection 

on a socket which already has one, or 
when trying to send a datagram with 
the destination address specified and 
the socket is already connected. 

[ENOTCONN] when trying to send a datagram, but no 

destination address is specified, and the 
socket hasn't been connected. 

[ENOBUFS] when the system runs out of memory 

for an internal data structure. 

[eaddrnot avail] when an attempt is made to create a 
socket with a network address for 
which no network interface exists. 

SEE ALSO 

send(2N), recv(2N), intro(5), inet(5F). 
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BUGS 

One should be able to send and receive ip options. 

The protocol should be settable after socket creation. 
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NAME 

lo — software loopback network interface 

SYNOPSIS 

pseudo-device loop 

DESCRIPTION 

The loop interface is a software loopback mechanism which may 
be used for performance analysis, software testing, and/or local 
communication. By default, the loopback interface is accessible 
at address 127.0.0.1 (nonstandard); mis address may be changed 
with the SIOCSIFADDR ioctl. 

DIAGNOSTICS 

lo%d: can't handle af%d. The interface was handed a 
message with addresses formatted in an unsuitable address family; 
the packet was dropped. 

SEE ALSO 

intro(5), inet(5F). 

BUGS 

It should handle all address and protocol families. An approved 
network address should be reserved for this interface. 
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NAME 

man — macros for formatting entries in this manual 

SYNOPSIS 

nroff -man files 

trof f -man [-rsl]files 

DESCRIPTION 

These nrof f (1)/ trof f (1) macros are used to lay out the format 
of the entries of this manual. The default page size is 8.5"xl 1", 
with a 6.5"xl0" text area; the -rsl flag option reduces these di- 
mensions to 6"x9" and 4.75"x8.375", respectively; this option 
(which is not effective in nrof f (1)) also reduces the default type 
size from 10-point to 9-point, and the vertical line spacing from 
12-point to 10-point. The -rV2 flag option may be used to set 
certain parameters to values appropriate for certain Versatec 
printers: it sets the line length to 82 characters, the page length to 
84 lines, and it inhibits underlining. 

Any text argument below may be one to six "words". Double 
quotes (" ") may be used to include blanks in a "word". If text is 
empty, the special treatment is applied to the next line that con- 
tains text to be printed. For example, . I may be used to italicize 
a whole line, or . SM followed by . B to make small bold text. By 
default, hyphenation is turned off for nrof f (1), but remains on 
for trof f(l). 

Type font and size are reset to default values before each para- 
graph and after processing font- and size-setting macros, e.g., . I, 
. rb, . SM. Tab stops are neither used nor set by any macro ex- 
cept . DT and . th. 

Default units for indents in are ens. When in is omitted, the previ- 
ous indent is used. This remembered indent is set to its default 
value (7.2 ens in trof f (1), 5 ens in nroff- this corresponds to 
0.5" in the default page size) by . th, . P, and . RS, and restored 
by .RE. 

. TH t s c n Set the title and entry heading; t is the title, s is 

the section number, c is extra commentary, e.g., 
"local," n is new manual name. Invokes .DT 
(see below). 

. SH text Place subhead text, e.g., SYNOPSIS, here. 

. SS text Place sub-subhead text, e.g., "Options", here. 
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. B text Make text bold. 

. I text Make text italic. 

. SM text Make text 1 point smaller than default point 

size. 
.RI ab Concatenate roman a with italic b, and alternate 

these two fonts for up to six arguments. Similar 

macros alternate between any two of roman, 

italic, and bold: 

.IR .RB .BR .IB .BI 

. P Begin a paragraph with normal font, point size, 

and indent. . pp is a synonym for .P. 
. HP in Begin paragraph with hanging indent. 

. TP in Begin indented paragraph with hanging tag. 

The next line that contains text to be printed is 

taken as the tag. If the tag does not fit, it is 

printed on a separate line. 
. IP t in Same as . tp in with tag t\ often used to get an 

indented paragraph without a tag. 
. RS in Increase relative indent (initially zero). Indent 

all output an extra in units from the current left 

margin. 
. RE k Return to the £th relative indent level (initially, 

k=l; £=0 is equivalent to £=1); if k is omitted, 

return to the most recent lower indent level. 
. PM m Produces proprietary markings; see mm(l). 

.DT Restore default tab settings (every 7.2 ens in 

trof f(l), 5 ens in nrof f (1)). 
. PD v Set the interparagraph distance to v vertical 

spaces. If v is omitted, set the interparagraph 

distance to the default value (0.4v in trof f (1), 

lvinnroff(l)). 

The following strings are defined: 

\*R ® introff(l), (Reg.) in nrof f. 

\ * S Change to default type size. 

\ * ( Tm Trademark indicator. 

The following number registers are given default values by . TH: 

IN Left margin indent relative to subheads (default 

is 7.2 ens in trof f (1), 5 ens in nrof f (1)). 
LL Line length including IN. 

PD Current interparagraph distance. 
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EXAMPLES 

The man macros are provided to process manual pages already 
on-line at a given location and to enable users to make their own 
manual pages. The preceding section demonstrated the usage of 
the macros themselves; the following section provides examples 
of command lines typically used to process the completed files. 

man macros are designed to run with either nrof f or trof f . 
The first command line will process a file using only macros and 
nrof f requests: 

nroff -Tip -man file I lp 

The file is piped to the local line printer, lp. 

The next command line will process a file containing tables as 
well as macros and nroff requests: 

tbl | nroff -Tip -man file | col I lp 

Notice that before it is sent to the line printer, the output is first 
filtered through col, to process the reverse line feeds used by 

tbl. 

The final example is a command line that processes an unusual 
manual page, one using pic. If the manual pages created with 
man are intended for an on-line facility, components requiring 
trof f , such as pic (or grap) should be avoided since the aver- 
age installation of terminals will not be able to process typeset do- 
cuments. 

pic file | tbl | troff -Taps -man | typesetter 

grap precedes pic because it is a preprocessor to pic; the re- 
verse order, of course, will not format correctly. The file contains 
one or more tables, requiring tbl, but col is no longer necessary 
because typeset documents do not use reverse line feeds with 
which to make tables. The -T flag option for specifying the out- 
put device (terminal type) takes the argument aps here, readying 
the document for processing on the APS-5 phototypesetter. 

CAVEATS 

Special macros, strings, and number registers exist, internal to 
man, in addition to those mentioned above. Except for names 
predefined by trof f(l) and number registers d, m, and y, all 
such internal names are of the form XA, where X is one of ) , ] , 
and } , and A stands for any alphanumeric character. 
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The programs that prepare the table of contents and the permuted 
index for this manual assume the NAME section of each entry 
consists of a single line of input that has the following format: 

name[, name, name . . .] V explanatory text 

The macro package increases the interword spaces (to eliminate 
ambiguity) in the SYNOPSIS section of each entry. 

The macro package itself uses only the roman font (so that one 
can replace, for example, the bold font by the constant-width font 
(CW). Of course, if the input text of an entry contains requests for 
other fonts (e.g., . I, . RB, \f I), the corresponding fonts must be 
mounted. 

FILES 

/usr/lib/tmac/tmac . an 
/usr/lib/macros/cmp.n. [dt] .an 
/usr/lib/macros/ucmp. n. an 

SEE ALSO 

eqn(l), man(l), tbl(l), tc(l), trof f (1). 

"Other Text Processing Tools" in AIUX Text Processing Tools. 

BUGS 

If the argument to . TH contains any blanks and is not enclosed by 
double quotes (" "), there will be strange irregular dots on the out- 
put. 
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NAME 

math' 



math functions and constants 



SYNOPSIS 

♦include <math.h> 

DESCRIPTION 

This file contains declarations of all the functions in the Math Li- 
brary (described in Section 3M), as well as various functions in 
the C Library (Section 3C) that return floating-point values. 

It defines the structure and constants used by the matherr(3M) 
error-handling mechanisms, including the following constant used 
as an error-return value. 

HUGE The maximum value of a double- 

precision floating-point number. 

The following mathematical constants are defined for user con- 
venience. 

M_E The base of natural logarithms (e). 

M_LOG2 E The base-2 logarithm of e. 

M_LOGl E The base- 10 logarithm of e. 

M_LN2 The natural logarithm of 2. 

M_LN1 The natural logarithm of 10. 

M_PI The ratio of the circumference of a circle 

to its diameter. (There are also several 
fractions of its reciprocal and its square 
root.) 

M_S QRT 2 The positive square root of 2. 

M_S QRT 1_2 The positive square root of 1/2. 

For the definitions of various machine-dependent "constants," 
see the description of the <values . h> header file. 

FILES 

/usr/include/math. h 

SEE ALSO 

intro(3),matherr(3M), values(5). 
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NAME 

me — macros for formatting papers 

SYNOPSIS 

nrof f -me [nrojf-options...] 
trof f -me [troff-options...] 

DESCRIPTION 

me is a package of nrof f and trof f macro definitions that pro- 
vides a canned formatting facility for technical papers in various 
formats. When producing two-column output on a terminal, filter 
the output through col(l). 

The macro requests are defined below. Many nrof f and trof f 
requests are unsafe in conjunction with this package; however, 
these requests may be used with impunity after the first . pp: 

Begin a new page. 

Break the output line here. 

Insert n spacing lines. 

Line spacing: n=i single, n=2 double space. 

No alignment of right margin. 

Center the next n lines. 

Underline the next n lines. 

Add n to the point size. 

Output of the eqn, neqn, refer, and tbl preprocessors for 
equations and tables is acceptable as input. 

FILES 

/usr/lib/tmac/tmac . e 
/usr/lib/me/* 

SEE ALSO 

eqn(l), trof f (1), ref er(l), tbl(l). 

AIUX Text Processing Tools. 

REQUESTS 

In the following list, initialization refers to the first .pp, .lp, 
. ip, . np, . sh, or . uh macro. This list is incomplete. 

MACRO INITIAL BREAK? EXPLANATION 
NAME VALUE RESET? 



br 




sp 


n 


Is 


n 


na 




ce 


n 


ul 


n 


sz 


+n 



c 


- 


yes 


Begin centered block. 


d 


- 


no 


Begin delayed text. 


f 


- 


no 


Begin footnote. 


1 


- 


yes 


Begin list. 
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■ q 


yes 


JC. z — 


no 


.c — 


yes 


.d 


yes 


.f 


yes 


.1 


yes 


• q 


yes 


.x — 


yes 


. z — 


yes 


.++mH - 


no 



,+c T 



yes 



lc 


1 


yes 


2c 


1 


yes 


EN 


- 


yes 


EQxy 


- 


yes 



GE 


- 


yes 


GS 


- 


yes 


PE 


- 


yes 


PS 


- 


yes 


TE 


- 


yes 


TH 


- 


yes 


TSx 


- 


yes 


ac AN 


- 


no 


b x 


no 


no 


ban 





yes 


be 


no 


yes 


bi* 


no 


no 


bu 


- 


yes 


bxx 


no 


no 


ef x'y'z 


*"" 


no 



Begin major quote. 

Begin floating keep. 

End centered block. 

End delayed text. 

End footnote. 

End list. 

End major quote. 

End index item. 

End floating keep. 

Define paper section, m defines the part of the 

paper, and can be C (chapter), A (appendix), P 

(preliminary, for example, anabstract, table of contents, and so on.), 

B (bibliography), RC (chapters renumbered from page 

of one each chapter), or 

RA (appendix renumbered from page one). 

Begin chapter (appendix, and so on, as set by . ++). . 

T is the chapter title. 

One-column format on a new page. 

Two-column format. 

Space after equation produced by eqn or neqn. 

Precede equation; break out and add space. The equation 

number is y. The optional argument x may be / to indent the 

equation (default), L to left-adjust the equation, or C to 

center the equation. 

End gremlin picture. 

Begin gremlin picture. 

End pic picture. 

Begin pic picture. 

End table. 

End heading section of table. 

Begin table; if x is H the table has a repeated heading. 

Set up for ACM style output. A is the Author's name(s), 

N is the total number of pages. 

Must be given before the first initialization. 

Print x in boldface; if no argument, switch to boldface. 

Augment the base indent by n. This indent is used to set 

the indent on regular text (like paragraphs). 

Begin new column. 

Print x in bold italics (no-fill only). 

Begin bulleted paragraph. 

Print x in a box (nofill only). 

Set even footer to x y z. 
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Set even header to x y z. 
Set footer to x y z. 

Suppress headers and footers on next page. 
Set header to x y z. 
Draw a horizontal line. 
Italicize x, if x missing, italic text follows. 
Start indented paragraph, with hanging tag x. Indentation 
is y ens (default 5). 
Start left-blocked paragraph. 

Read in a file of local macros of the form * x. Must be given 
before initialization. 
Start numbered paragraph. 
Set odd footer to x y z. 
Set odd header to x y z. 
Print delayed text. 

Begin paragraph with the first line indented. 
Roman text follows. 
Reset tabs to default values. 

Read in a file of special characters and diacritical marks. Must be 
given before initialization. 
sh x - yes Section head follows, font automatically bold, n is the level of section, 

and x is the title of the section. 

Leave the next page blank. Only one page is remembered ahead. 
Set x in a smaller point size. 
Augment the point size by n points. 

Produce the paper in thesis format. Must be given before initialization. 
Begin title page. 

Underline argument, even in t r o f f . (No-fill only). 
Like . sh but unnumbered. 
Print index x. 



eh'x'y'z "" 


no 


fo'x'y'z 


no 


hx 


no 


he'x'y'z "" 


no 


hi 


yes 


ix no 


no 


ipxy no 


yes 


lp yes 


yes 


lo 


no 


np 1 


yes 


of 'x'y'z 


no 


oh'x'y'z 


no 


pd 


yes 


pp no 


yes 


r yes 


no 


re 


no 


sc no 


no 



sk 


no 


no 


sm x 


- 


no 


sz +n 


lOp 


no 


th 


no 


no 


tp 


no 


yes 


ux 


- 


no 


uh 


- 


yes 


xpx 


- 


no 
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NAME 

mm — macro package for formatting documents 

SYNOPSIS 

mm [options] {files] 

nrof f -mm [options] [files] 
n r o f f -cm [options] [files] 
mmt [options] [files] 
t r o f f -mm [options] [files] 

DESCRIPTION 

This package provides a formatting capability for a very wide 
variety of documents. The manner in which you type and edit a 
document is essentially independent of whether the document is to 
be eventually formatted at a terminal or is to be phototypeset. 

Full details are provided in A/UX Text Processing Tools. 

FILES 

/usr/lib/tmac/tmac.m pointer to the noncompacted 

version of the package 

/usr /lib/macros /mm [nt] noncompacted version of the 

package 

SEE ALSO 

mm(l), mmt(l), nrof f (1), trof f (1). 

"mm Reference" in A/UX Text Processing Tools. 
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NAME 

mptx — the macro package for formatting a permuted index 

SYNOPSIS 

nrof f -mptx [options] [files] 

trof f -mptx [options] [files] 

DESCRIPTION 

This package provides a definition for the . xx macro used for for- 
matting a permuted index as produced by ptx(l). This package 
does not provide any other formatting capabilities such as headers 
and footers. If these or other capabilities are required, the mptx 
macro package may be used in conjuction with the mm macro 
package. In this case, the -mptx flag option must be invoked 
after the -mm call. For example: 

nrof f -mm -mptx file 
or 

mm —mptx file 

FILES 

/usr/lib/tmac/tmac.ptx pointer to the macro pack- 

age 
/usr /lib/macros /ptx macro package 

SEE ALSO 

mm(l), nrof f (1), ptx(l), trof f (1), mm(5). 

"Other Text Processing Tools" in AIUX Text Processing Tools. 
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NAME 

ms — text formatting macros 

SYNOPSIS 

nrof f -ms [nroff-options. . .] 

troff -ms [tr off-options. . .] 

DESCRIPTION 

This package of nrof f and troff macro definitions provides a 
formatting facility for various styles of articles, theses, and books. 
When producing 2-column output on a terminal or lineprinter, or 
when reverse line motions are needed, filter the output through 
col(l). All external ms macros are defined below. Many 
nrof f and troff requests are unsafe in conjunction with this 
package. However, the first four requests below may be used with 
impunity after initialization, and the last two may be used even be- 
fore initialization: 

. bp begin new page 

. br break output line 

. sp n insert n spacing lines 

. ce n center next n lines 

.Is n line spacing: n=\ single, n=2 double space 

. na no alignment of right margin 

Font and point size changes with \ f and \ s are also allowed; for 
example, \f lword\fP will produce word. Output of the tbl, 
eqn, and ref er(l) preprocessors for equations, tables, and refer- 
ences is acceptable as input. 

Full details are provided in A/UX Text Processing Tools. 

FILES 

/usr/lib/tmac/tmac.x 
/usr/lib/ms/x. ??? 

SEE ALSO 

eqn(l), ref er(l), tbl(l), trof f (1). 

"ms Reference" in A/UX Text Processing Tools. 

REQUESTS 

MACRO INITIAL BREAK? EXPLANATION 
NAME VALUE RESET? 

.ABx - y begin abstract; ifx=no don't label abstract 

. AE - y end abstract 

.AI - y author's institution 
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.AU 


- 


y 


.Bi 


- 


n 


.Bl 


- 


y 


.B2 


- 


y 


.BT 


date 


n 


.BXx 


- 


n 


.CM 


ift 


n 


.CT 


- 


y,y 


.DAx 


ifn 


n 


.DE 


- 


y 


.DSx y 


I 


y 


.ID y 


8n,.5i 


y 


.LD 


- 


y 


.CD 


- 


y 


.BD 


- 


y 


.EFx 


- 


n 


.EH* 


- 


n 


.EN 


- 


y 


.EQx y 


- 


y 


.FE 


- 


n 


.FP 


- 


n 


.FSx 


- 


n 


.HD 


undef 


n 


.Ix 


- 


n 


.IP x y 


- 


y.y 


. IXjc y 


- 


y 


.KE 


- 


n 


.KF 


- 


n 


.KS 


- 


y 


.LG 


- 


n 


.LP 


- 


y.y 


.MCx 


- 


y.y 


.NDx 


ift 


n 


.NHiy 


- 


y.y 


.NL 


lOp 


n 


.OFx 


- 


n 


.OHx 


- 


n 


.PI 


if TM 


n 


.PP 


- 


y.y 


.PT 


-%- 


n 


.PXx 


- 


y 


• QP 


- 


y.y 



author's name 

embolden x; if no x, switch to boldface 

begin text to be enclosed in a box 

end boxed text and print it 

bottom title, printed at foot of page 

print word x in a box 

cut mark between pages 

chapter title: page number moved to CF (TM only) 

force date x at bottom of page; today if no x 

end display (unfilled text) of any kind 

begin display with keep; x=I,L,C,B; y=indent 

indented display with no keep; y=indent 

left display with no keep 

centered display with no keep 

block display; center entire block 

even page footer x (3 part as for . 1 1 ) 

even page header* (3 part as for . 1 1) 

end displayed equation produced by eqn 

break out equation; x=L,I,C; y=equation number 

end footnote to be placed at bottom of page 

numbered footnote paragraph; may be redefined 

start footnote; x is optional footnote label 

optional page header below header margin 

italicize x; if no x, switch to italics 

indented paragraph, with hanging tag xr, y=indent 

index words x y and so on (up to 5 levels) 

end keep of any kind 

begin floating keep; text fills remainder of page 

begin keep; unit kept together on a single page 

larger, increase point size by 2 

left (block) paragraph. 

multiple columns; x=column width 

no date in page footer, x is date on cover 

numbered header, x=level, x=0 resets, x=S sets to y 

set point size back to normal 

odd page footer x (3 part as for . 1 1 ) 

odd page header x (3 part as for . tl) 

print header on 1st page 

paragraph with first line indented 

page title, printed at head of page 

print index (table of contents); x=no suppresses title 

quote paragraph (indented and shorter) 
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.R on n return to Roman font 

. RE 5n y,y retreat: end level of relative indentation 

. RP x - n released paper format; x=no stops title on 1 st page 

. RS 5n y,y right shift: start level of relative indentation 

. SH - y,y section header, in boldface 

. SM — n smaller, decrease point size by 2 

. TA 8n,5n n set tabs to 8n 16n ... (nrof f)5n lOn ... (trof f) 

. TC x — y print table of contents at end; x=no suppresses title 

. TE - y end of table processed by tbl 

.TH — y end multi-page header of table 

. TL - y title in boldface and two points larger 

. TM off n thesis mode 

. TSx - y,y begin table; if x=H table has multi-page header 

.ULx — n underline x (trof f) 

. UXx - n UNIX; trademark message first time; x appended 

. X A x y - y another index entry; x=page or no for none; y=indent 

. XE — y end index entry (or series of . IX entries) 

. XP — y.y paragraph with first line exdented, others indented 

. XS x y — y begin index entry; x=page or no for none; y=indent 

. 1C on y,y one column format, on a new page 

. 2C — y,y begin two column format 

. ] - — n beginning of refer reference 

. [ - n end of unclassifiable type of reference 

. [N - n N= l:journal-article, 2:book, 3:book-article, 4:report 

REGISTERS 

Formatting distances can be controlled in ms by means of built-in 

number registers. For example, this sets the line length to 6.5 
inches: 

. nr LL 6.5i 

Here is a table of number registers and their default values: 



PS 


point size 


paragraph 


10 


vs 


vertical spacing 


paragraph 


12 


LL 


line length 


paragraph 


6i 


LT 


title length 


next page 


same as LL 


FL 


footnote length 


next .FS 


5.5i 


PD 


paragraph distance paragraph 


lv(ifn),.3v(ift) 


DD 


display distance 


displays 


lv(ifn),.5v(ift) 


PI 


paragraph indent 


paragraph 


5n 


QI 


quote indent 


next . QP 


5n 


FI 


footnote indent 


next .FS 


2n 
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PO page offset next page (if n), ~li (if t) 

hm header margin next page li 

FM footer margin next page li 

FF footnote format next .FS 0(1,2, 3 available) 

When resetting these values, make sure to specify the appropriate 
units. Setting the line length to 7, for example, will result in out- 
put with one character per line. Setting FF to 1 suppresses foot- 
note superscripting; setting it to 2 also suppresses indentation of 
the first line; and setting it to 3 produces an . IP -like footnote 
paragraph. 

Here is a list of string registers available in ms; they may be used 
anywhere in the text: 

NAME STRING'S FUNCTION 



\*Q 


quote (" in nrof f, " in trof f) 


\*U 


unquote (" in nrof f, " in trof f) 


\*- 


dash (-in nroff, — in trof f) 


\* (MO 


month (month of the year) 


\* (DY 


day (current date) 


\ ** 


automatically numbered footnote 


\*' 


acute accent (before letter) 


\*« 


grave accent (before letter) 


\** 


circumflex (before letter) 


\*, 


cedilla (before letter) 


\*: 


umlaut (before letter) 


\*~ 


tilde (before letter) 



BUGS 

Floating keeps and regular keeps are diverted to the same space, 
so they cannot be mixed together with predictable results. 



February, 1990 
Revision C 



mv(5) mv(5) 



NAME 

mv — a trof f macro package for typesetting viewgraphs and 
slides 

SYNOPSIS 

mvt [-a] [options] [files] 

trof f [-a] [-rXl] -mv [options] [files] 

DESCRIPTION 

This package makes it easy to typeset viewgraphs and projection 
slides in a variety of sizes. A few macros (briefly described 
below) accomplish most of the formatting tasks needed in making 
transparencies. All of the facilities of t rof f (1), eqn(l), tbl(l), 
pic(l), and grap(l) are available for more difficult tasks. 

The output can be previewed on most terminals, and, in particular, 
on the TEKTRONIX 4014. For this device, specify the -rXl op- 
tion (this option is automatically specified by the mvt command 
when that command is invoked with the -D4 1 4 option). To pre- 
view output on other terminals, specify the -a option. 

The available macros are: 

. VS [n] [i] [d] Foil-start macro; foil size is to be 7"x7"; n is 
the foil number, i is the foil identification, d is 
the date; the foil-start macro resets all parame- 
ters (indent, point size, etc.) to initial default 
values, except for the values of i and d argu- 
ments inherited from a previous foil-start mac- 
ro; it also invokes the . A macro (see below). 

The naming convention for this and the fol- 
lowing eight macros is that the first character 
of the name (V or S) distinguishes between 
viewgraphs and slides, respectively, while the 
second character indicates whether the foil is 
square (S), small wide (w), small high (h), big 
wide (w), or big high (h). Slides are "skin- 
nier" than the corresponding viewgraphs: the 
ratio of the longer dimension to the shorter one 
is larger for slides than for viewgraphs. As a 
result, slide foils can be used for viewgraphs, 
but not vice versa; on the other hand, view- 
graphs can accommodate a bit more text. 
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. Vw [n] [i] [d] Same as . vs, except that foil size is 7" wide x 
5" high. 

. Vh [n] [i] [d] Same as . vs, except that foil size is 5"x7". 

. vw [n] [i] [d] Same as . VS, except that foil size is 7"x5.4". 

. VH [n] [i] [d\ Same as . VS, except that foil size is 7"x9". 

. Sw [n] [i] [d] Same as . vs, except that foil size is 7"x5". 

. Sh [n] [i] [d] Same as . VS, except that foil size is 5"x7". 

• SW [n] [/] [d] Same as . VS, except that foil size is 7"x5.4". 

. SH [n] [i] [d] Same as . VS, except that foil size is 7"x9". 

.A [x] Place text that follows at the first indentation 

level (left margin); the presence of x 
suppresses the V2 line spacing from the preced- 
ing text. 

. B [m [s] ] Place text that follows at the second indenta- 
tion level; text is preceded by a mark; m is the 
mark (default is a large bullet); s is the incre- 
ment or decrement to the point size of the 
mark with respect to the prevailing point size 
(default is 0); if s is 100, it causes the point 
size of the mark to be the same as that of the 
default mark. 

. C [m [s] ] Same as . B, but for the third indentation level; 
default mark is a dash. 

. D [m [s] ] Same as . B, but for the fourth indentation lev- 
el; default mark is a small bullet. 

. T string string is printed as an oversize, centered title. 

. I [in] [a [x] ] Change the current text indent (does not affect 
titles); in is the indent (in inches unless dimen- 
sioned, default is 0); if in is signed, it is an in- 
crement or decrement; the presence of a in- 
vokes the . A macro (see below) and passes x 
(if any) to it. 

- S [/?][/] Set the point size and line length; p is the point 

size (default is "previous"); Up is 100, the 
point size reverts to the initial default for the 
current foil-start macro; if p is signed, it is an 
increment or decrement (default is 18 for . vs, 
. VH, and . SH, and 14 for the other foil-start 
macros); / is the line length (in inches unless 
dimensioned; default is 42" for . vh, 3.8" for 
. Sh, 5" for . SH, and 6" for the other foil-start 
macros). 
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. DF n f [n f . . .] Define font positions; may not appear within a 
foil's input text (i.e., it may only appear after 
all the input text for a foil, but before the next 
foil-start macro); n is the position of font/; up 
to four "n /" pairs may be specified; the first 
font named becomes the prevailing font; the 
initial setting is (H is a synonym for G): 

DF1H2I3B4S 

.dv [a][b][c][d\ 

Alter the vertical spacing between indentation 
levels; a is the spacing for . A, b is for . B, c is 
for . c, and d is for . D; all nonnull arguments 
must be dimensioned; null arguments leave the 
corresponding spacing unaffected; initial set- 
ting is: 

DV 5v 5v 5v Ov 

. U strl [str2] Underline strl and concatenate str2 (if any) to 
it. 

The last four macros in the above list do not cause a break; the . I 
macro causes a break only if it is invoked with more than one ar- 
gument; all the other macros cause a break. 

The macro package also recognizes the following uppercase 
synonyms for the corresponding lowercase trof f requests: 

AD BR CE FI HY NA NF NH NX SO SP 
TA TI 

The Tm string produces the trademark symbol. 

The input tilde ( ~ ) character is translated into a blank on output. 

See the user's manual cited below for further details. 

FILES 

/usr/lib/tmac/tmac . v 
/usr /lib/macros /vmca 

SEE ALSO 

eqn(l), mmt(l), tbl(l), trof f (1). 

"Other Text Processing Tools" in AIUX Text Processing Tools. 
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NAME 

nterm — terminal driving tables for nrof f 

DESCRIPTION 

nrof f (1) uses driving tables to customize its output for various 
types of output devices, such as printing terminals, special word 
processing terminals (such as Diablo, Qume, or NEC Spinwriter 
mechanisms), or special output filter programs. These driving 
tables are written as ASCII files, and are installed in 
/usr/lib/nterm/tab.name, where name is the name for 
that terminal type as given in term(5). 

The first line of a driving table should contain the name of the ter- 
minal: simply a string with no embedded white space, "white 
space" means any combination of spaces, tabs and newlines. The 
next part of the driver table is structured as follows: 

bset [integer] (not supported in all versions of nrof f ) 

breset [integer] (not supported in all versions of nrof f ) 

Hor [integer] 

Vert [integer] 

Newline [integer] 

Char [integer] 

Em [integer] 

Half line [integer] 

Adj [integer] 

twinit [character-string] 

t wrest [character-string] 

twnl [character-string] 

hlr [character-string] 

hlf [character-string] 

fir [character-string] 

bdon [character-string] 

bdof f [character-string] 

it on [character-string] 

it of f [character-string] 

ploton [character-string] 

plotof f [character-string] 

up [character-string] 

down [character-string] 

right [character-string] 

left [character-string] 
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The meanings of these fields are as follows: 

bset bits to set in the c_of lag field of the termio 

structure before output. 

breset bits to reset in the c_of lag field of the ter- 
mio structure before output. 

Hor horizontal resolution in units of 1/240 of an 

inch. 

Vert vertical resolution in units of 1/240 of an inch. 

Newline space moved by a newline (linefeed) character 
in units of 1/240 of an inch. 

Char quantum of character sizes, in units of 1/240 of 

an inch. (That is, a character is a multiple of 
Char units wide) 

Em size of an em in units of 1/240 of an inch. 

Half line space moved by a half-linefeed (or half- 
reverse-linefeed) character in units in 1/240 of 
an inch. 

Adj quantum of white space, in 1/240 of an inch, 

(i.e., white spaces are a multiple of Adj units 
wide) 

Note: If this is less than the size of the 
space character, nroff will output 
fractional spaces using plot mode. Also, 
if the -e switch to nroff is Used, Adj 
is set equal to Hor by nroff. 

twinit sequence of characters used to initialize the ter- 
minal in a mode suitable for nroff . 

t w r e s t sequence of characters used to restore the termi- 
nal to normal mode. 

twnl sequence of characters used to move down one 

line. 

hlr sequence of characters used to move up one- 

half line. 

hlf sequence of characters used to move down 

one-half line. 
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fir sequence of characters used to move up one 

line. 

bdon sequence of characters used to turn on hardware 

boldface mode, if any. 

bdoff sequence of characters used to turn off 
hardware boldface mode, if any. 

it on sequence of characters used to turn on hardware 

italics mode, if any. 

it off sequence of characters used to turn off 
hardware italics mode, if any. 

plot on sequence of characters used to turn on hardware 
plot mode (for Diablo type mechanisms), if any. 

plot off sequence of characters used to turn off 
hardware plot mode (for Diablo type mechan- 
isms), if any. 

up sequence of characters used to move up one 

resolution unit (Vert) in plot mode, if any. 

down sequence of characters used to move down one 

resolution unit (Vert) in plot mode, if any. 

right sequence of characters used to move right one 

resolution unit (Hor) in plot mode, if any. 

left sequence of characters used to move left one 

resolution unit (Hor) in plot mode, if any. 

This part of the driving table is fixed format, and you cannot 
change the order of entries. You should put entries on 
separate lines, and these lines should contain exactly two 
fields (no comments allowed) separated by white space. For 
example, 

Cbset 
breset 
Hor 24 

and so on. 

Follow this first part of the driving table with a line contain- 
ing the word "charset," and then specify a table of spe- 
cial characters that you want to include. That is, specify all 
the non-ASCII characters that nrof f (1) knows by two char- 
acter names, such as -. If nrof f does not find the word 
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"charset" where it expects to, it will abort with an error 
message. 

Each definition in the part after "charset" occupies one 
line, and has the following format: 

chname width output 

where "chname"''' is the (two letter) name of the special char- 
acter, "width" is its width in ems, and "output" is the string 
of characters and escape sequences to send to the terminal to 
produce the special character. 

If any field in the "charset" part of the driving table does 
not pertain to the output device, you may give that particular 
sequence as a null string, or leave out the entry. Special 
characters that do not have a definition in this file are ignored 
on output by nrof f (1). 

You may put the "char set" definitions in any order, so it 
is possible to speed up nrof f by putting the most used char- 
acters first. For example, 

charset 
em 1 - 
hy 1 - 
\- 1 - 
bu 1 + 

and so on. 

The best way to create a terminal table for a new device is to 
take an existing terminal table and edit it to suit your needs. 
Once you create such a file, put it in the directory 
/usr/lib/nterm, and give it the name tab.xyz where 
xyz is the name of the terminal and the name that you pass 
nrof f via the -T flag option (for example, nrof f -Txyz). 

FILES 

/usr/lib/nterm/tab.name 

SEE ALSO 

nroff(l). 
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NAME 

prof — profile within a function 

SYNOPSIS 

tdefine MARK 
#include <prof.h> 

void MARK (name) 

DESCRIPTION 

mark will introduce a mark called name that will be treated the 
same as a function entry point. Execution of the mark will add to a 
counter for that mark, and program-counter time spent will be ac- 
counted to the immediately preceding mark or to the function if 
there are no preceding marks within the active function. 

name may be any combination of up to six letters, numbers or un- 
derscores. Each name in a single compilation must be unique, but 
may be the same as any ordinary program symbol. 

For marks to be effective, the symbol mark must be defined be- 
fore the header file <prof . h> is included. This may be defined 
by a preprocessor directive as in the synopsis, or by a command 
line argument, i.e: 

CC -p -DMARK f OO . C 

If MARK is not defined, the MARK (name) statements may be left in 
the source files containing them and will be ignored. 

EXAMPLES 

In this example, marks can be used to determine how much time is 
spent in each loop. Unless this example is compiled with mark 
defined on the command line, the marks are ignored. 

♦include <prof.h> 



foo( ) 
{ 



int 



MARK(loopl) ; 

for (i = 0; i < 2000; i++) { 



} 
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MARK(loop2) ; 

for (j = 0; j < 2000; j++) { 

} 
} 

SEE ALSO 

prof(l), profil(2), monitor(3C). 
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NAME 

regexp — regular expression compile and match routines 

SYNOPSIS 

# define INIT declarations 

#define GETC() getc-code 

#define PEEKCO peekc-code 

#define UNGETC (c) ungetc-code 

# define RETURN (pointer) return-code 

#define ERROR (val) errors-code 

#include <regexp.h> 

char * compile Unstring, expbuf, endbuf, eof) 
char *instring, *expbuf, *endbuf; 

int eof ; 

int step (string, exbuf) 
char * string, * exbuf; 

extern char *locl, *loc2, *locs; 

extern int circf, sed, nbra; 

DESCRIPTION 

This page describes general-purpose regular expression matching 
routines in the form of ed(l), defined in 
/usr/include/regexp. h. Programs such as ed(l), sed(l), 
grep(l), bs(l), expr(l), etc., which perform regular expression 
matching use this source file. In this way, only this file need be 
changed to maintain regular expression compatibility. 

The interface to this file is unpleasantly complex. Programs that 
include this file must have the following five macros declared be- 
fore the tinclude <regexp . h> statement. These macros are 
used by the compile routine. 

GETC ( ) Return the value of the next character in 

the regular expression pattern. Succes- 
sive calls to GETC ( ) should return suc- 
cessive characters of the regular expres- 
sion. 

PEEKC ( ) Return the next character in the regular 

expression. Successive calls to 
PEEKC ( ) should return the same charac- 
ter (which should also be the next charac- 
ter returned by GETC ( ) ). 
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UNGETC(C) 



RETURN (pointer) 



ERROR (val) 



ERROR 

11 

16 

25 
36 
41 
42 
43 
44 
45 
46 
49 
50 



Cause the argument c to be returned by 
the next call to GETCO (and 
peekc ( ) ). No more that one character 
of pushback is ever needed and this char- 
acter is guaranteed to be the last charac- 
ter read by getc ( ) . The value of the 
macro UNGETC(c) is always ignored. 

This macro is used on normal exit of the 
compile routine. The value of the ar- 
gument pointer is a pointer to the charac- 
ter after the last character of the compiled 
regular expression. This is useful to pro- 
grams which have memory allocation to 
manage. 

This is the abnormal return from the 
compile routine. The argument val is 
an error number (see table below for 
meanings). This call should never return. 

MEANING 

Range endpoint too large. 
Bad number. 
\digit out of range. 
Illegal or missing delimiter. 
No remembered search string. 
\ ( \ ) imbalance. 
Too many \ (. 

More than 2 numbers given in \ { \ } . 
} expected after \. 

First number exceeds second in \ { \ } . 
[ ] imbalance. 
Regular expression overflow. 



The syntax of the compile routine is as follows: 

compile (instring, expbuf, endbuf, eof) 

The first parameter instring is never used explicitly by the com- 
pile routine but is useful for programs that pass down different 
pointers to input characters. It is sometimes used in the init de- 
claration (see below). Programs which call functions to input 
characters or have characters in an external array can pass down a 
value of ((char *) 0) for this parameter. 
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The next parameter expbuf is a character pointer. It points to the 
place where the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where 
the compiled regular expression may be placed. If the compiled 
expression cannot fit in (endbuf-expbuf) bytes, a call to ER- 
ROR (50) is made. 

The parameter eof is the character which marks the end of the reg- 
ular expression. For example, in ed(l), this character is usually a 
/. 

Each program that includes this file must have a # define state- 
ment for I nit. This definition will be placed right after the de- 
claration for the function compile and the opening curly brace 
( { ). It is used for dependent declarations and initializations. Most 
often it is used to set a register variable to point the beginning of 
the regular expression so that this register variable can be used in 
the declarations for GETC ( ) , peekc ( ) , and ungetc ( ) . Other- 
wise it can be used to declare external variables that might be used 
by GETC ( ) , PEEKC ( ) , and UNGETC ( ) . See the example below 
of the declarations taken from grep(l). 

There are other functions in this file which perform actual regular 
expression matching, one of which is the function step. The call 
to step is as follows: 

s t ep ( string , expbuf) 

The first parameter to step is a pointer to a string of characters to 
be checked for a match. This string should be null terminated. 

The second parameter expbuf is the compiled regular expression 
which was obtained by a call of the function compile. 

The function step returns non-zero if the given string matches 
the regular expression, and zero if the expressions do not match. 
If there is a match, two external character pointers are set as a side 
effect to the call to step. The variable set in step is loci. 
This is a pointer to the first character that matched the regular ex- 
pression. The variable loc2, which is set by the function ad- 
vance, points to the character after the last character that 
matches the regular expression. Thus if the regular expression 
matches the entire line, loci will point to the first character of 
string and loc2 will point to the null at the end of string. 
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step uses the external variable circf which is set by compile 
if the regular expression begins with ". If this is set then step 
will try to match the regular expression to the beginning of the 
string only. If more than one regular expression is to be compiled 
before the first is executed the value of circf should be saved 
for each compiled expression and circf should be set to that 
saved value before each call to step. 

The function advance is called from step with the same argu- 
ments as step. The purpose of step is to step through the 
string argument and call advance until advance returns non- 
zero indicating a match or until the end of string is reached. If 
one wants to constrain string to the beginning of the line in all 
cases, step need not be called; simply call advance. 

When advance encounters a * or \ { \ } sequence in the regu- 
lar expression, it will advance its pointer to the string to be 
matched as far as possible and will recursively call itself trying to 
match the rest of the string to the rest of the regular expression. 
As long as there is no match, advance will back up along the 
string until it finds a match or reaches the point in the string that 
initially matched the * or \ { \ } . It is sometimes desirable to 
stop this backing up before the initial point in the string is reached. 
If the external character pointer Iocs is equal to the point in the 
string at sometime during the backing up process, advance will 
break out of the loop that backs up and will return zero. This is 
used by ed(l) and sed(l) for substitutions done globally (not just 
the first occurrence, but the whole line) so, for example, expres- 
sions like s/y*//gdo not loop forever. 

The additional external variables sed and nbra are used for spe- 
cial purposes. 

EXAMPLES 

The following is an example of how the regular expression macros 
and calls look from grep(l): 

#define INIT register char *sp=instring; 

#define GETC() (*sp++) 

#define PEEKC() (*sp) 

#define UNGETC (c) (~sp) 

#def ine RETURN (c) return; 

#define ERROR (c) regerrO 

# include <regexp.h> 

(void) compile (*argv, expbuf , Sexpbuf [ESIZE] , ' \0' ) ; 
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if (step (linebuf,expbuf ) ) 
succeed ( ) ; 

FILES 

/usr/include/regexp.h 

SEE ALSO 

bs(l), ed(l), expr(l), grep(l), sed(l). 

BUGS 

The handling of circf is awkward. 
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NAME 

stat — data returned by stat system call 

SYNOPSIS 

#include <sys/types .h> 
#include <sys/stat.h> 

DESCRIPTION 

The system calls stat and f stat return data whose structure is 
defined by this include file. The encoding of the field st_mode is 
defined in this file also. 



/< 



* Structure of the result of stat 
*/ 



struct 
{ 


stat 

dev t 

ino t 

ushort 

short 

short 

short 

dev t 

off_t 

time t 

int 

time t 

int 

time t 

int 

long 

long 


st dev; 
st ino; 
st mode; 
st nlink; 
st uid; 
st gid; 
st rdev; 
st size; 
st atime; 
st sparel; 
st mtime; 
st spare2; 
st ctime; 
st spare3; 
st_blksize; 
st blocks; 






}; 


long 


st spare4 [2] ; 




#define 


S IFMT 


0170000 


/* 


type of file */ 


#def ine 


S_IFDIR 


0040000 


/* 


directory */ 


tdefine 


S IFCHR 


0020000 


/* 


character special */ 


#define 


S_IFBLK 


0060000 


/* 


block special */ 


#def ine 


S IFREG 


0100000 


/* 


regular */ 


#def ine 


S_IFIFO 


0010000 


/* 


FIFO */ 


#def ine 


S IFLNK 


0120000 


/* 


symbolic link */ 


#def ine 


S IFSOC 


0140000 


/* 


socket */ 


#def ine 


S ISUID 


04000 


/* 


set user ID on execution */ 


#def ine 


S_ISGID 


02000 


/* 


set group ID on execution */ 


tdefine 


S_ISVTX 


01000 


/* 


save swapped text even 
after use */ 


#define 


S I READ 


00400 


/* 


read permission, owner */ 


tdefine 


S_IWRIT 


00200 


/* 


write permission, owner */ 
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#define S_IEXEC 00100 

#define S_IRUSR 00400 
#define S_IWUSR 00200 
#define S_IXUSR 00100 

#define S IRWXU (S IRUSR 



/* execute/search permission, 

owner */ 
/* read permission, owner */ 
/* write permission, owner */ 
/* execute/search permission, 

owner */ 
S IWUSR | S IXUSR) 



#define 
#def ine 
#define 



S_IRGRP 00040 
S_IWGRP 00020 
S IXGRP 00010 



#define S IRWXG (S IRGRP 



/* read permission, group */ 
/* write permission, group */ 
/* execute/search permission, 

group */ 
S IWGRP | S IXGRP) 



#define 
#define 
#define 



S_IROTH 00004 
S_IWOTH 00002 
S IXOTH 00001 



#define S IRWXO (S IROTH 



/* read permission, others */ 
/* write permission, others */ 
/* execute/search permission, 

others */ 
S IWOTH | S IXOTH) 



FILES 

/usr/include/sys/types . h 
/usr/include/sys/stat .h 

SEE ALSO 

stat(2), types(5). 
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NAME 

tcp — Internet Transmission Control Protocol 

SYNOPSIS 

tinclude <sys/socket .h> 
finclude <netinet/in.h> 

S = socket (AF_INET, SOCK_STREAM, 0); 

DESCRIPTION 

The TCP protocol provides reliable, flow-controlled, two-way 
transmission of data. It is a byte-stream protocol used to support 
the SOCK_STREAM abstraction. TCP uses the standard Internet 
address format and, in addition, provides a per-host collection of 
"port addresses". Thus, each address is composed of an Internet 
address specifying the host and network, with a specific TCP port 
on the host identifying the peer entity. 

Sockets utilizing the tcp protocol are either "active" or "pas- 
sive". Active sockets initiate connections to passive sockets. By 
default TCP sockets are created active; to create a passive socket 
the listen(2N) system call must be used after binding the sock- 
et with the bind(2N) system call. Only passive sockets may use 
the accept(2N) call to accept incoming connections. Only ac- 
tive sockets may use the connect(2N) call to initiate connec- 
tions. 

Passive sockets may "underspecify" their location to match in- 
coming connection requests from multiple networks. This tech- 
nique, termed "wildcard addressing," allows a single server to 
provide service to clients on multiple networks. To create a sock- 
et which listens on all networks, the Internet address 
INADDR_ANY must be bound. The TCP port may still be 
specified at this time; if the port is not specified the system will as- 
sign one. Once a connection has been established the socket's ad- 
dress is fixed by the peer entity's location. The address assigned 
the socket is the address associated with the network interface 
through which packets are being transmitted and received. Nor- 
mally this address corresponds to the peer entity's network. 

ERRORS 

A socket operation may fail with one of the following errors re- 
turned: 

[EISCONN] when trying to establish a connection on 

a socket which already has one; 
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[ENOBUFS] 



[ETIMEDOUT] 



[ECONNRESET] 



[ECONNREFUSED] 



[EADDRINUSE] 



[EADDRNOTAVAIL] 



when the system runs out of memory for 
an internal data structure; 

when a connection was dropped due to 
excessive retransmissions; 

when the remote peer forces the connec- 
tion to be closed; 

when the remote peer actively refuses 
connection establishment (usually be- 
cause no process is listening to the port); 

when an attempt is made to create a sock- 
et with a port which has already been al- 
located; 

when an attempt is made to create a sock- 
et with a network address for which no 
network interface exists. 



SEE ALSO 

intro(5), inet(5F). 

BUGS 

It should be possible to send and receive TCP options. The sys- 
tem always tries to negotiates the maximum TCP segment size to 
be 1024 bytes. This can result in poor performance if an interven- 
ing network performs excessive fragmentation. 
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NAME 

term — conventional names for terminals 

DESCRIPTION 

These names are used by certain commands (e.g., nroff(l), 
mm(l), man(l), tabs(l)) and are maintained as part of the shell 
environment (see sh(l), prof ile(4), and environ(5)) in the 
variable $term: 



1520 

1620 

1620-12 

2621 

2631 

263 1-c 

2631-e 

2640 

2645 

300 

300-12 

300s 

382 

300s-12 

3045 

33 

37 

40-2 

40-4 

4540 

3270 

4000a 

4014 

43 

450 

450-12 

735 

745 

dumb 

sync 

hp 
lp 



Datamedia 1520 

Diablo 1620 and others using the HyType II printer 

same, in 12-pitch mode 

Hewlett-Packard HP2621 series 

Hewlett-Packard 2631 line printer 

Hewlett-Packard 2631 line printer - compressed mode 

Hewlett-Packard 2631 line printer - expanded mode 

Hewlett-Packard HP2640 series 

Hewlett-Packard HP264n series (other than the 2640 series) 

DASI/DTC/GSI 300 and others using the HyType I printer 

same, in 12-pitch mode 

DASI/DTC/GSI 300s 

DTC 382 

same, in 12-pitch mode 

Datamedia 3045 

TELETYPE Terminal Model 33 KSR 

TELETYPE Terminal Model 37 KSR 

TELETYPE Terminal Model 40/2 

TELETYPE Terminal Model 40/4 

TELETYPE Terminal Model 4540 

IBM Model 3270 

Trendata 4000a 

Tektronix 4014 

TELETYPE Model 43 KSR 

DASI 450 (same as Diablo 1620) 

same, in 12-pitch mode 

Texas Instruments TI735 and TI725 

Texas Instruments TI745 

generic name for terminals that lack reverse 

linefeed and other special escape sequences 

generic name for synchronous TELETYPE 

4540-compatible terminals 

Hewlett-Packard (same as 2645) 

generic name for a line printer 
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tnl200 General Electric TermiNet 1200 
tn300 General Electric TermiNet 300 

Up to 8 characters, chosen from [-a-z0-9], make up a basic ter- 
minal name. Terminal submodels and operational modes are dis- 
tinguished by suffixes beginning with a -. Names should general- 
ly be based on original vendors, rather than local distributors. A 
terminal acquired from one vendor should not have more than one 
distinct basic name. 

Commands whose behavior depends on the type of terminal 
should accept arguments of the form -Tterm where term is one of 
the names given above; if no such argument is present, such com- 
mands should obtain the terminal type from the environment vari- 
able $TERM, which, in turn, should contain term. 

See /etc/termcap on your system for a complete list. 

SEE ALSO 

mm(l), nroff(l), sh(l), stty(l), tabs(l), tplot(lG), 
profile(4), environ(5). 

BUGS 

This is a small candle trying to illuminate a large, dark problem. 
Programs that ought to adhere to this nomenclature do so some- 
what fitfully. 
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NAME 

trof f — description of trof f output language 

DESCRIPTION 

The device-independent trof f outputs a pure ASCII description 
of a typeset document. The description specifies the typesetting 
device, the fonts, and the point sizes of characters to be used as 
well as the position of each character on the page. A list of all the 
legal commands follows. Most numbers are denoted as n and are 
ASCII strings. Strings inside of brackets ([]) are optional. 
troff may produce them, but they are not required for the 
specification of the language. The character \n has the standard 
meaning of "newline" character. Between commands, white 
space has no meaning. White space characters are spaces and 
newlines. 



sn 



in 



ex 



Cxyz 



Rn 



The point size of the characters to be 
generated. 

The font mounted in the specified posi- 
tion is to be used. The number ranges 
from to the highest font presently 
mounted. is a special position, invoked 
by trof f , but not directly accessible to 
the troff user. Normally fonts are 
mounted starting at position 1. 

Generate the character x at the current lo- 
cation on the page; x is a single ASCII 
character. 

Generate the special character xyz. The 
name of the character is delimited by 
white space. The name will be one of the 
special characters legal for the typeset- 
ting device as specified by the device 
specification found in the file desc. 
This file resides in a directory specific for 
the typesetting device. (See f ont(5) and 
/usr/lib/font/dev*.) 

Change the horizontal position on the 
page to the number specified. The 
number is in basic units of motions as 
specified by DESC. This is an absolute 
"goto". 
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hn Add the number specified to the current 

horizontal position. This is a relative 
"goto". 

Vn Change the vertical position on the page 

to the number specified (down is posi- 
tive). 

vai Add the number specified to the current 

vertical position. 

nnx This is a two-digit number followed by 

an ASCII character. The meaning is a 
combination of hn followed by ex. The 
two digits nn are added to the current 
horizontal position and then the ASCII 
character, x, is produced. This is the 
most common form of character 
specification. 

nb a This command indicates that the end of a 

line has been reached. No action is re- 
quired, though by convention the hor- 
izontal position is set to 0. trof f will 
specify a resetting of the x,y coordinates 
on the page before requesting that more 
characters be printed. The first number, 
b, is the amount of space before the line 
and the second number, a, the amount of 
space after the line. The second number 
is delimited by white space. 

w Aw appears between words of the input 

document. No action is required. It is in- 
cluded so that one device can be emulat- 
ed more easily on another device. 

pn Begin a new page. The new page 

number is included in this command. 
The vertical position on the page should 
be set to 0. 

# .... \n A line beginning with a pound sign is a 

comment. 

Dl x v\n Draw a line from the current location to 

x,y. 
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Dc d\n 



De dx dy\n 



Da x y u v 



D~ x y x y...\n 



x i [nit] \n 



x T device \n 



x r [es] n h v\n 



Draw a circle of diameter d with the left- 
most edge being at the current location 
(x, y). The current location after drawing 
the circle will be x+d,y, the rightmost 
edge of the circle. 

Draw an ellipse with the specified axes. 
dx is the axis in the x direction and dy is 
the axis in the y direction. The leftmost 
edge of the ellipse will be at the current 
location. After drawing the ellipse the 
current location will be x+dx,y. 

Draw a counterclockwise arc from the 
current location to x+u,y+v using a circle 
of whose center is x,y from the current 
location. The current location after 
drawing the arc will be at its end. 

Draw a spline curve (wiggly line) 
between each of the x,y coordinate pairs 
starting at the current location. The final 
location will be the final x,y pair of the 
list 

Initialize the typesetting device. The ac- 
tions required are dependent on the dev- 
ice. An init command will always oc- 
cur before any output generation is at- 
tempted. 

The name of the typesetter is device. 
This is the same as the argument to the 
-T option. The information about the 
typesetter will be found in the directory 

/usr/lih/£ont/dev{device} . 

The resolution of the typesetting device 
in increments per inch is n. Motion in the 
horizontal direction can take place in un- 
its of h basic increments. Motion in the 
vertical direction can take place in units 
of v basic increments. For example, the 
APS -5 typesetter has a basic resolution of 
723 increments per inch and can move in 
either direction in 723rds of an inch. Its 
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specification is: 

x res 723 1 1 

Pause. Cause the current page to finish 
but do not relinquish the typesetter. 

Stop. Cause the current page to finish 
and then relinquish the typesetter. Per- 
form any shutdown and bookkeeping 
procedures required. 

Generate a trailer. On some devices no 
operation is performed. 

Load the font name into position n. 

Set the character height to n points. This 
causes the letters to be elongated or shor- 
tened. It does not affect the width of a 
letter. 

x S[lant] «\n Set the slant to n degrees. Only some 

typesetters can do this and not all angles 
are supported. 

SEE ALSO 

troff(l). 

"nrof f/trof f Reference" and "Introduction to trof f and 

mm" in A/UX Text Processing Toots. 



x p[ause] \n 
x s [top] \n 

x t [railer] \n 

x f [ont] nname\n 
x H [eight] n\n 
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NAME 

types — primitive system data types 

SYNOPSIS 

finclude <sys/types .h> 

DESCRIPTION 

The data types defined in the include file are used in A/UX® sys- 
tem code; some data of these types are accessible to user code: 

#ifndef sys_types_h 

♦define sys_types_h 

/* 

* System-dependent parameters and types 

*/ 

typedef char *caddr_t; 

typedef long clock_t; 

typedef short cnt_t; 

typedef long daddr_t; 

typedef unsigned short dev_t; 

typedef short gid_t; 

typedef unsigned short ino__t; 

typedef long key_t; 

typedef int label_t[13]; 

typedef unsigned short mode_t; 

typedef short nlink_t; 

typedef long off_t; 

typedef long paddr_t; 

typedef int pid_t; 

typedef int ptrdiff_t; 

typedef int size_t; 

typedef long time_t; 

typedef long ubadr_t; 

typedef unsigned char uchar_t; 

typedef unsigned short ushort_t; 

typedef short uid_t; 

typedef unsigned int uint_t; 

typedef unsigned long ulong_t; 

typedef unsigned int wchar_t; 

#ifndef NULL 
tdefine NULL 
#endif /* NULL */ 
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/* 

*To be excluded from visibility control, 
types must end in _t . 
*/ 
#ifdef _SYSV_SOURCE 
typdef unsigned int uint; 
typdef unsigned long ulong; 
typdef unsigned char unchar; 
typdef unsigned short ushort; 
#endif /* _SYSV_SOURCE */ 

#ifdef _BSD_SOURCE 

typedef struct fd_set { long fds_bits[l]; } fd_set; 

typedef struct{int r[l]/} *physadr; 

typedef struct _quad{ long val[2]; } quad; 

typedef unsigned char u_char; 

typedef unsigned short u_short; 

typedef unsigned int u_int; 

typedef unsigned long u__long; 

#endif /* _BSD_SOURCE */ 

#ifdef _AUX_SOURCE 
typedef unisigned long ino_tl; 
#endif /* _AUX_SOURCE */ 
#endif /* ! sys_types_h */ 

The form daddr_t is used for disk addresses except in an inode 
on disk (see f s(4)). Times are encoded in seconds since 00:00:00 
GMT, January 1, 1970. The major and minor parts of a device 
code specify kind and unit number of a device and are 
installation-dependent. Offsets are measured in bytes from the be- 
ginning of a file. The label_t variables are used to save the 
processor state while another process is running. 

SEE ALSO 

fs(4). 
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NAME 

udp — Internet User Datagram Protocol 

SYNOPSIS 

♦include <sys/socket .h> 
♦include <netinet/in.h> 

S=SOCket (AF_INET, SOCK_DGRAM, 0); 

DESCRIPTION 

UDP is a simple, unreliable datagram protocol which is used to 
support the SOCK_DGRAM abstraction for the Internet protocol 
family. UDP sockets are connectionless, and are normally used 
with the sendto and recvfrom calls, though the 
connect(2N) call may also be used to fix the destination for fu- 
ture packets (in which case the recv(2N) or send(2N) system 
calls may be used). 

UDP address formats are identical to those used by TCP. In par- 
ticular UDP provides a port identifier in addition to the normal In- 
ternet address format. Note that the UDP port space is separate 
from the TCP port space (i.e., a UDP port may not be "connect- 
ed" to a TCP port). In addition broadcast packets may be sent 
(assuming the underlying network supports this) by using a 
reserved "broadcast address"; this address is network interface 
dependent. 

ERRORS 

A socket operation may fail with one of the following errors re- 
turned: 

[EISCONN] when trying to establish a connection on 

a socket which already has one, or when 
trying to send a datagram with the desti- 
nation address specified and the socket is 
already connected; 

[ENOTCONN] when trying to send a datagram, but no 

destination address is specified, and the 
socket hasn't been connected; 

[ENOBUFS ] when the system runs out of memory for 

an internal data structure; 

[ EADDRINUSE ] when an attempt is made to create a sock- 

et with a port which has already been al- 
located; 
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[EADDRNOTAVAIL] 



when an attempt is made to create a sock- 
et with a network address for which no 
network interface exists. 



SEE ALSO 

send(2N), recv(2N), intro(5), inet(5F). 
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NAME 

values — machine-dependent values 

SYNOPSIS 

#include <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined 
for particular processor architectures. 

The model assumed for integers is binary representation (one's or 
two's complement), where the sign is represented by the value of 
the high-order bit. 

bits (type) 

The number of bits in a specified type (for example, int). 

HIBITS 

The value of a short integer with only the high-order bit set 
(in most implementations, 0x8000). 

HIBITL 

The value of a long integer with only the high-order bit set 
(in most implementations, 0x80000000). 

HIBITI 

The value of a regular integer with only the high-order bit set 
(usually the same as HIBITS orHiBiTL). 

MAX SHORT 

The maximum value of a signed short integer (in most imple- 
mentations, 0x7FFF = 32767). 

MAX LONG 

The maximum value of a signed long integer (in most imple- 
mentations, 0x7FFFFFFF = 2147483647). 

MAX I NT 

The maximum value of a signed regular integer (usually the 
same as maxshort or maxlong). 

MAXFLOAT, LN_MAXFLOAT 

The maximum value of a single-precision floating-point 
number, and its natural logarithm. 

MAXDOUBLE, LN_MAXDOUBLE 

The maximum value of a double-precision floating-point 
number, and its natural logarithm. 
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MINFLOAT, LN_MINFLOAT 

The minimum positive value of a single-precision floating- 
point number, and its natural logarithm. 

MINDOUBLE, LN_MINDOUBLE 

The minimum positive value of a double-precision floating- 
point number, and its natural logarithm. 

FSIGNIF 

The number of significant bits in the mantissa of a single- 
precision floating-point number. 

DSIGNIF 

The number of significant bits in the mantissa of a double- 
precision floating-point number. 

FILES 

/usr/include/values . h 

SEE ALSO 

intro(3), math(5). 
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